world-building-framework 0.0.0-stage → 0.2.0

package/dist/core/schema/describe.js

@@ -0,0 +1,51 @@
+import { commonFieldsSchema, entityFrontmatterSchema, eventFrontmatterSchema } from "./fields.js";
+const FIELD_MEANINGS = {
+    type: 'Top-level kind: "entity" or "event".',
+    title: "Human-readable display name (required — 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: "Optional in-world date anchor: { year, day }.",
+    entities: "The entities this event is tied to.",
+};
+function shapeKeys(schema) {
+    return Object.keys(schema.shape);
+}
+function describeFields(names) {
+    return names.map((name) => `  - ${name}: ${FIELD_MEANINGS[name] ?? "(see SCHEMA.md)"}`);
+}
+/**
+ * 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 function describeSchema(entityTypeVocabulary) {
+    const commonKeys = shapeKeys(commonFieldsSchema);
+    const excluded = new Set([...commonKeys, "type"]);
+    const entityKeys = shapeKeys(entityFrontmatterSchema).filter((key) => !excluded.has(key));
+    const eventKeys = shapeKeys(eventFrontmatterSchema).filter((key) => !excluded.has(key));
+    const lines = [
+        "Common fields (every file):",
+        ...describeFields(["type", ...commonKeys]),
+        "",
+        "Entity-only fields:",
+        ...describeFields(entityKeys),
+        "",
+        "Event-only fields:",
+        ...describeFields(eventKeys),
+        "",
+        'Any other frontmatter field whose value is a wikilink ("[[uuid|Display Name]]") 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.");
+    }
+    return lines.join("\n");
+}

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

@@ -0,0 +1,249 @@
+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.ZodEffects<z.ZodString, string, string>;
+export declare const inWorldDateSchema: z.ZodObject<{
+    year: z.ZodNumber;
+    day: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    year: number;
+    day: number;
+}, {
+    year: number;
+    day: number;
+}>;
+/** 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, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    tags?: string[] | undefined;
+    aliases?: string[] | undefined;
+}, {
+    title: string;
+    tags?: string[] | undefined;
+    aliases?: string[] | undefined;
+}>;
+export declare const entityFrontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const eventFrontmatterSchema: z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, z.ZodTypeAny, "passthrough">>;
+export declare const knowledgeFileFrontmatterSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, z.ZodTypeAny, "passthrough">>, z.ZodObject<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, z.ZodTypeAny, "passthrough">>]>, z.objectOutputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, z.ZodTypeAny, "passthrough"> | z.objectOutputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"entity">;
+    entityType: z.ZodOptional<z.ZodString>;
+    supersedes: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    causedBy: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+}, z.ZodTypeAny, "passthrough"> | z.objectInputType<{
+    title: z.ZodString;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    aliases: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+} & {
+    type: z.ZodLiteral<"event">;
+    after: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+    date: z.ZodOptional<z.ZodObject<{
+        year: z.ZodNumber;
+        day: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        year: number;
+        day: number;
+    }, {
+        year: number;
+        day: number;
+    }>>;
+    entities: z.ZodOptional<z.ZodArray<z.ZodEffects<z.ZodString, string, string>, "many">>;
+}, z.ZodTypeAny, "passthrough">>;
+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(),
+})
+    .passthrough();
+export const eventFrontmatterSchema = commonFieldsSchema
+    .extend({
+    type: z.literal("event"),
+    after: z.array(wikilinkSchema).optional(),
+    date: inWorldDateSchema.optional(),
+    entities: z.array(wikilinkSchema).optional(),
+})
+    .passthrough();
+export const knowledgeFileFrontmatterSchema = z
+    .discriminatedUnion("type", [entityFrontmatterSchema, eventFrontmatterSchema])
+    .superRefine((data, ctx) => {
+    if (data.type === "entity" && Boolean(data.supersedes) !== Boolean(data.causedBy)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.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;

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