world-building-framework 0.0.0-stage → 0.2.0

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[];

package/dist/core/lint/dangling-links.js

@@ -0,0 +1,46 @@
+import { isWikilink, parseWikilink } from "../schema/wikilink.js";
+function extractFrontmatterLinks(value, path, out) {
+    if (typeof value === "string" && isWikilink(value)) {
+        out.push({ path, targetId: parseWikilink(value).targetId });
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, i) => extractFrontmatterLinks(entry, `${path}[${i}]`, out));
+    }
+}
+const BODY_WIKILINK_RE = /\[\[([0-9a-f-]{36})\|[^\]]*\]\]/gi;
+function extractBodyLinkTargets(body) {
+    return [...body.matchAll(BODY_WIKILINK_RE)].map((match) => match[1]);
+}
+/**
+ * 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 function findDanglingLinks(file, knownIds) {
+    const issues = [];
+    const frontmatterLinks = [];
+    for (const [key, value] of Object.entries(file.frontmatter)) {
+        extractFrontmatterLinks(value, key, frontmatterLinks);
+    }
+    for (const link of frontmatterLinks) {
+        if (!knownIds.has(link.targetId)) {
+            issues.push({
+                path: link.path,
+                message: `Dangling link: no file with id "${link.targetId}" exists in the vault`,
+                severity: "error",
+            });
+        }
+    }
+    for (const targetId of extractBodyLinkTargets(file.body)) {
+        if (!knownIds.has(targetId)) {
+            issues.push({
+                path: "body",
+                message: `Dangling link: no file with id "${targetId}" exists in the vault`,
+                severity: "error",
+            });
+        }
+    }
+    return issues;
+}

package/dist/core/lint/events-without-entities.d.ts

@@ -0,0 +1,4 @@
+import type { VaultFile } from "../vault/types.js";
+import type { ValidationIssue } from "../schema/validate.js";
+/** Flags an event with no `entities` — SCHEMA.md's own example of a plausible lint rule. A warning, not an error: an event may be written before its entities exist. */
+export declare function findEventsWithoutEntities(file: Pick<VaultFile, "frontmatter">): ValidationIssue[];

package/dist/core/lint/events-without-entities.js

@@ -0,0 +1,9 @@
+/** Flags an event with no `entities` — SCHEMA.md's own example of a plausible lint rule. A warning, not an error: an event may be written before its entities exist. */
+export function findEventsWithoutEntities(file) {
+    if (file.frontmatter.type !== "event")
+        return [];
+    const entities = file.frontmatter.entities;
+    if (Array.isArray(entities) && entities.length > 0)
+        return [];
+    return [{ path: "entities", message: "Event has no entities — consider tying it to at least one", severity: "warning" }];
+}

package/dist/core/lint/forked-versions.d.ts

@@ -0,0 +1,14 @@
+import type { VaultFile } from "../vault/types.js";
+import type { ValidationIssue } from "../schema/validate.js";
+/** The id a file's `supersedes` points at, if it's a valid wikilink. */
+export declare function supersedesTarget(frontmatter: Record<string, unknown>): string | undefined;
+/**
+ * Flags a version that supersedes a file some other version already supersedes —
+ * a fork in the entity's version chain. A warning, not an error: the data model
+ * allows story branches (GD-1), but the v1 wiki renders a single story, so a fork
+ * is far more often a version pointed at an older predecessor than at the latest.
+ * `supersededBy` maps each file id to the ids of the vault files superseding it.
+ */
+export declare function findForkedVersions(file: Pick<VaultFile, "frontmatter"> & {
+    id?: string;
+}, supersededBy: Map<string, string[]>): ValidationIssue[];

package/dist/core/lint/forked-versions.js

@@ -0,0 +1,29 @@
+import { isWikilink, parseWikilink } from "../schema/wikilink.js";
+/** The id a file's `supersedes` points at, if it's a valid wikilink. */
+export function supersedesTarget(frontmatter) {
+    const value = frontmatter.supersedes;
+    return isWikilink(value) ? parseWikilink(value).targetId : undefined;
+}
+/**
+ * Flags a version that supersedes a file some other version already supersedes —
+ * a fork in the entity's version chain. A warning, not an error: the data model
+ * allows story branches (GD-1), but the v1 wiki renders a single story, so a fork
+ * is far more often a version pointed at an older predecessor than at the latest.
+ * `supersededBy` maps each file id to the ids of the vault files superseding it.
+ */
+export function findForkedVersions(file, supersededBy) {
+    const target = supersedesTarget(file.frontmatter);
+    if (!target)
+        return [];
+    const others = (supersededBy.get(target) ?? []).filter((id) => id !== file.id);
+    if (others.length === 0)
+        return [];
+    return [
+        {
+            path: "supersedes",
+            message: `Fork in the version chain: ${others.join(", ")} also supersede${others.length === 1 ? "s" : ""} ${target}. ` +
+                "A new version should normally supersede the entity's latest version.",
+            severity: "warning",
+        },
+    ];
+}

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

@@ -0,0 +1,6 @@
+export * from "./dangling-links.js";
+export * from "./events-without-entities.js";
+export * from "./forked-versions.js";
+export * from "./after-loops.js";
+export * from "./target-types.js";
+export * from "./lint.js";

package/dist/core/lint/index.js

@@ -0,0 +1,6 @@
+export * from "./dangling-links.js";
+export * from "./events-without-entities.js";
+export * from "./forked-versions.js";
+export * from "./after-loops.js";
+export * from "./target-types.js";
+export * from "./lint.js";

package/dist/core/lint/lint.d.ts

@@ -0,0 +1,24 @@
+import type { VaultFile } from "../vault/types.js";
+import type { ValidationIssue } from "../schema/validate.js";
+/** Whole-vault facts some lint rules need. Build once per vault snapshot with createLintContext. */
+export interface LintContext {
+    knownIds: Set<string>;
+    /** File id -> ids of the files whose `supersedes` points at it. */
+    supersededBy: Map<string, string[]>;
+    /** Event id -> the ids its `after` points at. */
+    afterOf: Map<string, string[]>;
+    /** File id -> its frontmatter `type`. */
+    types: Map<string, unknown>;
+    /** File id -> title, for readable messages. */
+    titles: Map<string, string>;
+}
+export declare function createLintContext(files: VaultFile[]): LintContext;
+/**
+ * Runs every lint rule against one file. Pass the file's own `id` when it already
+ * exists in the vault (validate, update), so it isn't compared against itself.
+ */
+export declare function lintFile(file: Pick<VaultFile, "frontmatter" | "body"> & {
+    id?: string;
+}, context: LintContext): ValidationIssue[];
+/** Lints every file in a vault snapshot. Returns only files with at least one issue. */
+export declare function lintVault(files: VaultFile[]): Map<string, ValidationIssue[]>;

package/dist/core/lint/lint.js

@@ -0,0 +1,50 @@
+import { findDanglingLinks } from "./dangling-links.js";
+import { findEventsWithoutEntities } from "./events-without-entities.js";
+import { findForkedVersions, supersedesTarget } from "./forked-versions.js";
+import { findAfterLoops, afterTargets } from "./after-loops.js";
+import { findWrongTargetTypes } from "./target-types.js";
+export function createLintContext(files) {
+    const supersededBy = new Map();
+    const afterOf = new Map();
+    const titles = new Map();
+    for (const file of files) {
+        const target = supersedesTarget(file.frontmatter);
+        if (target)
+            supersededBy.set(target, [...(supersededBy.get(target) ?? []), file.id]);
+        if (file.frontmatter.type === "event")
+            afterOf.set(file.id, afterTargets(file.frontmatter));
+        if (typeof file.frontmatter.title === "string")
+            titles.set(file.id, file.frontmatter.title);
+    }
+    return {
+        knownIds: new Set(files.map((file) => file.id)),
+        supersededBy,
+        afterOf,
+        types: new Map(files.map((file) => [file.id, file.frontmatter.type])),
+        titles,
+    };
+}
+/**
+ * Runs every lint rule against one file. Pass the file's own `id` when it already
+ * exists in the vault (validate, update), so it isn't compared against itself.
+ */
+export function lintFile(file, context) {
+    return [
+        ...findDanglingLinks(file, context.knownIds),
+        ...findEventsWithoutEntities(file),
+        ...findForkedVersions(file, context.supersededBy),
+        ...findAfterLoops(file, context.afterOf, context.titles),
+        ...findWrongTargetTypes(file, context.types, context.titles),
+    ];
+}
+/** Lints every file in a vault snapshot. Returns only files with at least one issue. */
+export function lintVault(files) {
+    const context = createLintContext(files);
+    const result = new Map();
+    for (const file of files) {
+        const issues = lintFile(file, context);
+        if (issues.length > 0)
+            result.set(file.id, issues);
+    }
+    return result;
+}

package/dist/core/lint/target-types.d.ts

@@ -0,0 +1,9 @@
+import type { VaultFile } from "../vault/types.js";
+import type { ValidationIssue } from "../schema/validate.js";
+/**
+ * Flags each reserved relation whose target exists but is the wrong type. An
+ * error, since every case above silently breaks the wiki. Targets that don't
+ * exist at all are left to the dangling-link rule. `types` maps file id -> its
+ * frontmatter `type`.
+ */
+export declare function findWrongTargetTypes(file: Pick<VaultFile, "frontmatter">, types: Map<string, unknown>, titles: Map<string, string>): ValidationIssue[];

package/dist/core/lint/target-types.js

@@ -0,0 +1,47 @@
+import { isWikilink, parseWikilink } from "../schema/wikilink.js";
+/**
+ * Reserved relation fields whose targets must be a specific type (SCHEMA.md),
+ * keyed by the type of the file holding the field. The schema only checks the
+ * values are wikilinks; a wrong-typed target passes that and then misbehaves
+ * at render time:
+ * - `after` -> non-event: causal ordering fails.
+ * - `entities` -> non-entity: the event isn't tied to any entity.
+ * - `causedBy` -> non-event: merge never shows the version (its "causing event" is never included).
+ * - `supersedes` -> non-entity: the version is unreachable from any anchor, so it never renders.
+ * On any other file type these field names are just free-form relations.
+ */
+const REQUIRED_TARGET_TYPES = {
+    event: { after: "event", entities: "entity" },
+    entity: { causedBy: "event", supersedes: "entity" },
+};
+/**
+ * Flags each reserved relation whose target exists but is the wrong type. An
+ * error, since every case above silently breaks the wiki. Targets that don't
+ * exist at all are left to the dangling-link rule. `types` maps file id -> its
+ * frontmatter `type`.
+ */
+export function findWrongTargetTypes(file, types, titles) {
+    const fileType = file.frontmatter.type;
+    if (fileType !== "entity" && fileType !== "event")
+        return [];
+    const issues = [];
+    for (const [field, requiredType] of Object.entries(REQUIRED_TARGET_TYPES[fileType])) {
+        const value = file.frontmatter[field];
+        const entries = Array.isArray(value)
+            ? value.map((entry, i) => [`${field}[${i}]`, entry])
+            : [[field, value]];
+        for (const [path, entry] of entries) {
+            if (!isWikilink(entry))
+                continue;
+            const { targetId } = parseWikilink(entry);
+            if (!types.has(targetId) || types.get(targetId) === requiredType)
+                continue;
+            issues.push({
+                path,
+                message: `\`${field}\` must point at an ${requiredType}, but "${titles.get(targetId) ?? "untitled"}" (${targetId}) isn't one`,
+                severity: "error",
+            });
+        }
+    }
+    return issues;
+}

package/dist/core/query/dates.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+export declare const dateBoundSchema: z.ZodObject<{
+    year: z.ZodNumber;
+    day: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    year: number;
+    day?: number | undefined;
+}, {
+    year: number;
+    day?: number | undefined;
+}>;
+export type DateBound = z.infer<typeof dateBoundSchema>;
+export declare const dateRangeQuerySchema: z.ZodObject<{
+    from: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day?: number | undefined;
+    }, {
+        year: number;
+        day?: number | undefined;
+    }>>;
+    to: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day?: number | undefined;
+    }, {
+        year: number;
+        day?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    from?: {
+        year: number;
+        day?: number | undefined;
+    } | undefined;
+    to?: {
+        year: number;
+        day?: number | undefined;
+    } | undefined;
+}, {
+    from?: {
+        year: number;
+        day?: number | undefined;
+    } | undefined;
+    to?: {
+        year: number;
+        day?: number | undefined;
+    } | undefined;
+}>;
+export type DateRangeQuery = z.infer<typeof dateRangeQuerySchema>;
+/** An in-world date, as stored in an event's `date` field. */
+export interface DateTuple {
+    year: number;
+    day: number;
+}
+/** Negative if a is earlier than b, positive if later, 0 if the same date. */
+export declare function compareDates(a: DateTuple, b: DateTuple): number;
+/** True if a dated value falls within the range's bounds (inclusive). Either bound is optional. */
+export declare function isDateWithinRange(date: DateTuple, range: DateRangeQuery): boolean;
+/**
+ * True if a dated value is at or before the range's upper bound. Used for the
+ * entity/version inclusion gate — the lower bound never excludes entities
+ * (REQUIREMENTS.md: an entity introduced long ago can still be relevant now).
+ */
+export declare function isAtOrBeforeUpperBound(date: DateTuple, range: DateRangeQuery): boolean;
+/** True if a dated value is at or after the range's lower bound (or the range has none). */
+export declare function isAtOrAfterLowerBound(date: DateTuple, range: DateRangeQuery): boolean;

package/dist/core/query/dates.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export const dateBoundSchema = z.object({
+    year: z.number().int(),
+    day: z.number().int().optional(),
+});
+export const dateRangeQuerySchema = z.object({
+    from: dateBoundSchema.optional(),
+    to: dateBoundSchema.optional(),
+});
+function lowerTuple(bound) {
+    return { year: bound.year, day: bound.day ?? -Infinity };
+}
+function upperTuple(bound) {
+    return { year: bound.year, day: bound.day ?? Infinity };
+}
+/** Negative if a is earlier than b, positive if later, 0 if the same date. */
+export function compareDates(a, b) {
+    return a.year !== b.year ? a.year - b.year : a.day - b.day;
+}
+/** True if a dated value falls within the range's bounds (inclusive). Either bound is optional. */
+export function isDateWithinRange(date, range) {
+    if (range.from && compareDates(date, lowerTuple(range.from)) < 0)
+        return false;
+    if (range.to && compareDates(date, upperTuple(range.to)) > 0)
+        return false;
+    return true;
+}
+/**
+ * True if a dated value is at or before the range's upper bound. Used for the
+ * entity/version inclusion gate — the lower bound never excludes entities
+ * (REQUIREMENTS.md: an entity introduced long ago can still be relevant now).
+ */
+export function isAtOrBeforeUpperBound(date, range) {
+    if (!range.to)
+        return true;
+    return compareDates(date, upperTuple(range.to)) <= 0;
+}
+/** True if a dated value is at or after the range's lower bound (or the range has none). */
+export function isAtOrAfterLowerBound(date, range) {
+    if (!range.from)
+        return true;
+    return compareDates(date, lowerTuple(range.from)) >= 0;
+}

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

@@ -0,0 +1,2 @@
+export * from "./dates.js";
+export * from "./types.js";

package/dist/core/query/index.js

@@ -0,0 +1,2 @@
+export * from "./dates.js";
+export * from "./types.js";

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

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/**
+ * A named build variant's filter query (PROJECT_CONFIG.md #3): tags a file must
+ * carry, and/or an event date range. This is both the runtime shape the render
+ * pipeline filters against and the shape a vault's world.config.json validates
+ * its `buildVariants` entries against — one definition, no separate DSL to parse.
+ */
+export declare const buildVariantQuerySchema: z.ZodObject<{
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    dateRange: z.ZodOptional<z.ZodObject<{
+        from: z.ZodOptional<z.ZodObject<{
+            year: z.ZodNumber;
+            day: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            year: number;
+            day?: number | undefined;
+        }, {
+            year: number;
+            day?: number | undefined;
+        }>>;
+        to: z.ZodOptional<z.ZodObject<{
+            year: z.ZodNumber;
+            day: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            year: number;
+            day?: number | undefined;
+        }, {
+            year: number;
+            day?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        from?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+        to?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+    }, {
+        from?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+        to?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    tags?: string[] | undefined;
+    dateRange?: {
+        from?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+        to?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    tags?: string[] | undefined;
+    dateRange?: {
+        from?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+        to?: {
+            year: number;
+            day?: number | undefined;
+        } | undefined;
+    } | undefined;
+}>;
+export type BuildVariantQuery = z.infer<typeof buildVariantQuerySchema>;

package/dist/core/query/types.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { dateRangeQuerySchema } from "./dates.js";
+/**
+ * A named build variant's filter query (PROJECT_CONFIG.md #3): tags a file must
+ * carry, and/or an event date range. This is both the runtime shape the render
+ * pipeline filters against and the shape a vault's world.config.json validates
+ * its `buildVariants` entries against — one definition, no separate DSL to parse.
+ */
+export const buildVariantQuerySchema = z.object({
+    tags: z.array(z.string()).optional(),
+    dateRange: dateRangeQuerySchema.optional(),
+});

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

@@ -0,0 +1,8 @@
+/**
+ * Prints the live, current schema: field names come straight from the zod
+ * schemas in fields.ts, so this can't structurally drift from what
+ * validateFrontmatter actually enforces. This is what the CLI's `schema`
+ * command exposes so Claude always sees the real, current rules — see
+ * claude-dev/PROJECT_STRUCTURE.md.
+ */
+export declare function describeSchema(entityTypeVocabulary?: string[]): string;