world-building-framework 0.0.0-stage → 0.2.1

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,34 @@
+import { z } from "zod";
+export declare const dateBoundSchema: z.ZodObject<{
+    year: z.ZodNumber;
+    day: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+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>;
+    }, z.core.$strip>>;
+    to: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+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,21 @@
+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>>;
+    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>;
+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,34 @@
+/** Example `wbf create` inputs, one per kind. A test validates them, so they can't drift from the schema either. */
+export declare const SCHEMA_EXAMPLES: {
+    entity: {
+        frontmatter: {
+            type: string;
+            entityType: string;
+            title: string;
+            tags: string[];
+            home: string;
+        };
+        body: string;
+    };
+    event: {
+        frontmatter: {
+            type: string;
+            title: string;
+            date: {
+                year: number;
+                day: number;
+            };
+            after: string[];
+            entities: string[];
+        };
+        body: string;
+    };
+};
+/**
+ * Prints the live, current schema: field names and value shapes 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 an agent always sees the real, current rules — see
+ * claude-dev/PROJECT_STRUCTURE.md.
+ */
+export declare function describeSchema(entityTypeVocabulary?: string[]): string;

package/dist/core/schema/describe.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { commonFieldsSchema, entityFrontmatterSchema, eventFrontmatterSchema, wikilinkSchema, } from "./fields.js";
+const FIELD_MEANINGS = {
+    type: "Top-level kind.",
+    title: "Human-readable display name (filenames are UUIDs, this is the real name).",
+    tags: "Project-defined tags used for build-time filtering.",
+    aliases: "Alternate names/spellings, for search recall and Obsidian autocomplete only — not used for link resolution.",
+    entityType: "Category (e.g. character, location). Lint-checked against this vault's declared vocabulary, if any.",
+    supersedes: "Marks this file as a new version of an existing entity — points at the file it replaces.",
+    causedBy: "The event responsible for this version existing. Required alongside supersedes, and vice versa.",
+    after: "Causal predecessor event(s) — the required ordering/branching backbone.",
+    date: "In-world date anchor. Give both year and day.",
+    entities: "The entities this event is tied to.",
+};
+/** Example `wbf create` inputs, one per kind. A test validates them, so they can't drift from the schema either. */
+export const SCHEMA_EXAMPLES = {
+    entity: {
+        frontmatter: {
+            type: "entity",
+            entityType: "character",
+            title: "Alea Marrow",
+            tags: ["player"],
+            home: "[[66a7bd3f-a744-4565-acbe-006957625792|Port Kavas]]",
+        },
+        body: "Captain of the *Gull*.",
+    },
+    event: {
+        frontmatter: {
+            type: "event",
+            title: "The Great Storm",
+            date: { year: 150, day: 200 },
+            after: ["[[bb1ddebd-3a7c-4b6c-847a-b4de59a71e66|Alea takes command of the Gull]]"],
+            entities: ["[[adfdd8db-0bf1-4053-928f-52709232859f|Alea Marrow]]"],
+        },
+        body: "A three-day storm floods the lower docks.",
+    },
+};
+/** A schema's value shape in words, read from the zod schema itself. */
+function describeShape(schema) {
+    if (schema === wikilinkSchema)
+        return "link";
+    if (schema instanceof z.ZodOptional)
+        return describeShape(schema.unwrap());
+    if (schema instanceof z.ZodLiteral)
+        return schema.values.size === 1 ? JSON.stringify([...schema.values][0]) : "literal";
+    if (schema instanceof z.ZodString)
+        return "string";
+    if (schema instanceof z.ZodNumber)
+        return schema.isInt ? "integer" : "number";
+    if (schema instanceof z.ZodArray)
+        return `list of ${describeShape(schema.element)}s`;
+    if (schema instanceof z.ZodObject) {
+        const keys = Object.entries(schema.shape).map(([key, value]) => `${key}${value instanceof z.ZodOptional ? "?" : ""}: ${describeShape(value)}`);
+        return `{ ${keys.join(", ")} }`;
+    }
+    return "value";
+}
+function describeFields(shape, names) {
+    return names.map((name) => {
+        const schema = shape[name];
+        const required = schema instanceof z.ZodOptional ? "optional" : "required";
+        return `  - ${name} (${describeShape(schema)}, ${required}): ${FIELD_MEANINGS[name] ?? "(see SCHEMA.md)"}`;
+    });
+}
+/**
+ * Prints the live, current schema: field names and value shapes 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 an agent always sees the real, current rules — see
+ * claude-dev/PROJECT_STRUCTURE.md.
+ */
+export function describeSchema(entityTypeVocabulary) {
+    const commonKeys = Object.keys(commonFieldsSchema.shape);
+    const excluded = new Set([...commonKeys, "type"]);
+    const entityKeys = Object.keys(entityFrontmatterSchema.shape).filter((key) => !excluded.has(key));
+    const eventKeys = Object.keys(eventFrontmatterSchema.shape).filter((key) => !excluded.has(key));
+    const lines = [
+        "Common fields (every file):",
+        `  - type ("entity" or "event", required): ${FIELD_MEANINGS.type}`,
+        ...describeFields(commonFieldsSchema.shape, commonKeys),
+        "",
+        "Entity-only fields:",
+        ...describeFields(entityFrontmatterSchema.shape, entityKeys),
+        "",
+        "Event-only fields:",
+        ...describeFields(eventFrontmatterSchema.shape, eventKeys),
+        "",
+        'A link is a string "[[uuid|Display Name]]". A list field takes a list even for one link: after: ["[[uuid|Name]]"].',
+        "Any other frontmatter field whose value is a link is automatically a relation.",
+    ];
+    if (entityTypeVocabulary && entityTypeVocabulary.length > 0) {
+        lines.push("", `This vault's declared entityType vocabulary: ${entityTypeVocabulary.join(", ")}`);
+    }
+    else {
+        lines.push("", "This vault has not declared an entityType vocabulary — any entityType value is accepted.");
+    }
+    lines.push("", "Example input for `wbf create` (replace the UUIDs with real ids, e.g. from `wbf search`):", `  entity: ${JSON.stringify(SCHEMA_EXAMPLES.entity)}`, `  event:  ${JSON.stringify(SCHEMA_EXAMPLES.event)}`);
+    return lines.join("\n");
+}

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

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/** Any field whose value looks like this is auto-detected as a graph edge (SCHEMA.md rule 2) — no fixed vocabulary of relation-field names. */
+export declare const wikilinkSchema: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+export declare const inWorldDateSchema: z.ZodObject<{
+    year: z.ZodNumber;
+    day: z.ZodNumber;
+}, z.core.$strip>;
+/** Fields every knowledge file carries (SCHEMA.md "Common frontmatter"). */
+export declare const commonFieldsSchema: z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const entityFrontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    causedBy: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+}, z.core.$loose>;
+export declare const eventFrontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, z.core.$strip>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+}, z.core.$loose>;
+export declare const knowledgeFileFrontmatterSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+    causedBy: z.ZodOptional<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>;
+}, z.core.$loose>, z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, z.core.$strip>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>>>;
+}, z.core.$loose>], "type">;
+export type EntityFrontmatter = z.infer<typeof entityFrontmatterSchema>;
+export type EventFrontmatter = z.infer<typeof eventFrontmatterSchema>;
+export type KnowledgeFileFrontmatter = z.infer<typeof knowledgeFileFrontmatterSchema>;

package/dist/core/schema/fields.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { isWikilink } from "./wikilink.js";
+/** Any field whose value looks like this is auto-detected as a graph edge (SCHEMA.md rule 2) — no fixed vocabulary of relation-field names. */
+export const wikilinkSchema = z.string().refine(isWikilink, {
+    message: 'Expected a wikilink in the form "[[uuid|Display Name]]"',
+});
+export const inWorldDateSchema = z.object({
+    year: z.number().int(),
+    day: z.number().int(),
+});
+/** Fields every knowledge file carries (SCHEMA.md "Common frontmatter"). */
+export const commonFieldsSchema = z.object({
+    title: z.string().min(1, "title is required"),
+    tags: z.array(z.string()).optional(),
+    aliases: z.array(z.string()).optional(),
+});
+export const entityFrontmatterSchema = commonFieldsSchema
+    .extend({
+    type: z.literal("entity"),
+    entityType: z.string().optional(),
+    supersedes: wikilinkSchema.optional(),
+    causedBy: wikilinkSchema.optional(),
+})
+    .loose();
+export const eventFrontmatterSchema = commonFieldsSchema
+    .extend({
+    type: z.literal("event"),
+    after: z.array(wikilinkSchema).optional(),
+    date: inWorldDateSchema.optional(),
+    entities: z.array(wikilinkSchema).optional(),
+})
+    .loose();
+export const knowledgeFileFrontmatterSchema = z
+    .discriminatedUnion("type", [entityFrontmatterSchema, eventFrontmatterSchema])
+    .superRefine((data, ctx) => {
+    if (data.type === "entity" && Boolean(data.supersedes) !== Boolean(data.causedBy)) {
+        ctx.addIssue({
+            code: "custom",
+            message: '"supersedes" and "causedBy" must both be present, or both absent',
+            path: ["causedBy"],
+        });
+    }
+});

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

@@ -0,0 +1,4 @@
+export * from "./wikilink.js";
+export * from "./fields.js";
+export * from "./validate.js";
+export * from "./describe.js";

package/dist/core/schema/index.js

@@ -0,0 +1,4 @@
+export * from "./wikilink.js";
+export * from "./fields.js";
+export * from "./validate.js";
+export * from "./describe.js";

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

@@ -0,0 +1,22 @@
+import { type KnowledgeFileFrontmatter } from "./fields.js";
+export interface ValidationIssue {
+    path: string;
+    message: string;
+    /** "error" blocks a write and makes a file invalid; "warning" is a suggestion only. */
+    severity: "error" | "warning";
+}
+export declare function hasErrors(issues: ValidationIssue[]): boolean;
+export interface ValidationResult {
+    valid: boolean;
+    frontmatter?: KnowledgeFileFrontmatter;
+    issues: ValidationIssue[];
+}
+export interface ValidateOptions {
+    /** This project's declared entityType vocabulary (PROJECT_CONFIG.md). Omit to skip the check. */
+    entityTypeVocabulary?: string[];
+}
+/**
+ * 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 declare function validateFrontmatter(raw: unknown, options?: ValidateOptions): ValidationResult;