@wrenautomation/knowledge 0.0.0-stage → 0.58.0

package/dist/record-index.js

@@ -0,0 +1,247 @@
+/**
+ * The index: what a repo holds at one commit, in Postgres (or PGlite). Never the truth: rebuilt from
+ * git at will. A sync applies the diff from the last indexed commit to HEAD and the new head in one
+ * transaction, so a replay is safe and a crash leaves the old state. Rows carry `repo`: one index can
+ * hold many repos (a client each) for an admin view.
+ */
+import { and, desc, eq, ilike, inArray, or, sql } from "drizzle-orm";
+import { integer, jsonb, pgTable, primaryKey, text } from "drizzle-orm/pg-core";
+import { diff, head, isAncestor, tryGit } from "./git.js";
+import { edgesOf } from "./records.js";
+import { loadAt, RECORD_DIRS, readPathsAt } from "./repo.js";
+// bump when a table changes: the index drops and rebuilds itself from git
+const SCHEMA = "1";
+export const metaT = pgTable("knowledge_meta", { repo: text().notNull(), key: text().notNull(), value: text().notNull() }, (t) => [primaryKey({ columns: [t.repo, t.key] })]);
+export const recordsT = pgTable("knowledge_records", {
+    repo: text().notNull(),
+    id: text().notNull(),
+    type: text().notNull(),
+    title: text().notNull(),
+    status: text().notNull(),
+    version: integer().notNull(),
+    by: text().notNull(),
+    why: text().notNull(),
+    path: text().notNull(),
+    topic: text(),
+    source: text(),
+    body: text().notNull(),
+    data: jsonb().notNull(),
+    created: text().notNull(),
+    updated: text().notNull(),
+}, (t) => [primaryKey({ columns: [t.repo, t.id] })]);
+export const citesT = pgTable("knowledge_cites", { repo: text().notNull(), from: text().notNull(), to: text().notNull() }, (t) => [primaryKey({ columns: [t.repo, t.from, t.to] })]);
+const DDL = [
+    `create table if not exists knowledge_meta (repo text not null, key text not null, value text not null, primary key (repo, key))`,
+    `create table if not exists knowledge_records (repo text not null, id text not null, type text not null, title text not null, status text not null, version integer not null, "by" text not null, why text not null, path text not null, topic text, source text, body text not null, data jsonb not null, created text not null, updated text not null, primary key (repo, id))`,
+    `create index if not exists knowledge_records_path on knowledge_records (repo, path)`,
+    `create table if not exists knowledge_cites (repo text not null, "from" text not null, "to" text not null, primary key (repo, "from", "to"))`,
+    `create index if not exists knowledge_cites_to on knowledge_cites (repo, "to")`,
+];
+const DROP = [
+    "drop table if exists knowledge_cites",
+    "drop table if exists knowledge_records",
+    "drop table if exists knowledge_meta",
+];
+export class RecordIndex {
+    db;
+    close_;
+    ready = false;
+    constructor(db, close_ = async () => { }) {
+        this.db = db;
+        this.close_ = close_;
+    }
+    close() {
+        return this.close_();
+    }
+    /** Create the tables; a schema change drops and rebuilds them. */
+    async init() {
+        if (this.ready)
+            return;
+        for (const q of DDL)
+            await this.db.execute(sql.raw(q));
+        const [v] = await this.db
+            .select()
+            .from(metaT)
+            .where(and(eq(metaT.repo, "*"), eq(metaT.key, "schema")));
+        if (v?.value !== SCHEMA) {
+            for (const q of DROP)
+                await this.db.execute(sql.raw(q));
+            for (const q of DDL)
+                await this.db.execute(sql.raw(q));
+            await this.db.insert(metaT).values({ repo: "*", key: "schema", value: SCHEMA });
+        }
+        this.ready = true;
+    }
+    async indexedHead(repo) {
+        await this.init();
+        const [r] = await this.db
+            .select()
+            .from(metaT)
+            .where(and(eq(metaT.repo, repo), eq(metaT.key, "head")));
+        return r?.value ?? null;
+    }
+    /** Bring `repo` up to the checkout's HEAD. `full` rebuilds it from the files. */
+    async sync(root, repo, opts = {}) {
+        await this.init();
+        const h = head(root);
+        const last = opts.full ? null : await this.indexedHead(repo);
+        if (!h)
+            return { repo, head: null, mode: "none", upserted: 0, deleted: 0, broken: [] };
+        if (last === h)
+            return { repo, head: h, mode: "none", upserted: 0, deleted: 0, broken: [] };
+        const known = last && tryGit(root, ["cat-file", "-e", `${last}^{commit}`]).ok;
+        const incremental = !!(last && known && isAncestor(root, last, h));
+        let gone = [];
+        let removed = 0;
+        let tree;
+        if (incremental) {
+            const d = diff(root, last, h, RECORD_DIRS);
+            tree = readPathsAt(root, h, d.changed);
+            gone = [...d.deleted, ...d.changed];
+            removed = d.deleted.length;
+        }
+        else
+            tree = loadAt(root, h);
+        await this.db.transaction(async (tx) => {
+            if (!incremental) {
+                await tx.delete(citesT).where(eq(citesT.repo, repo));
+                removed = (await tx.delete(recordsT).where(eq(recordsT.repo, repo)).returning({ id: recordsT.id })).length;
+            }
+            else if (gone.length) {
+                const old = await tx
+                    .delete(recordsT)
+                    .where(and(eq(recordsT.repo, repo), inArray(recordsT.path, gone)))
+                    .returning({ id: recordsT.id });
+                const ids = old.map((o) => o.id);
+                if (ids.length)
+                    await tx.delete(citesT).where(and(eq(citesT.repo, repo), inArray(citesT.from, ids)));
+            }
+            for (const { path, doc } of tree.docs) {
+                const row = toRow(repo, path, doc.fm, doc.body);
+                await tx
+                    .insert(recordsT)
+                    .values(row)
+                    .onConflictDoUpdate({ target: [recordsT.repo, recordsT.id], set: row });
+                await tx.delete(citesT).where(and(eq(citesT.repo, repo), eq(citesT.from, doc.fm.id)));
+                const edges = edgesOf(doc.fm).map((to) => ({ repo, from: doc.fm.id, to }));
+                if (edges.length)
+                    await tx.insert(citesT).values(edges).onConflictDoNothing();
+            }
+            await tx
+                .insert(metaT)
+                .values({ repo, key: "head", value: h })
+                .onConflictDoUpdate({ target: [metaT.repo, metaT.key], set: { value: h } });
+        });
+        return {
+            repo,
+            head: h,
+            mode: incremental ? "diff" : "full",
+            upserted: tree.docs.length,
+            deleted: removed,
+            broken: tree.broken,
+        };
+    }
+    async get(repo, id) {
+        await this.init();
+        const [r] = await this.db
+            .select()
+            .from(recordsT)
+            .where(and(eq(recordsT.repo, repo), eq(recordsT.id, id)));
+        if (!r)
+            return null;
+        const cites = await this.linked(repo, id, "to");
+        const citedBy = await this.linked(repo, id, "from");
+        return { record: r, cites, citedBy };
+    }
+    /** other = "to": what `id` cites; "from": what cites `id`. */
+    async linked(repo, id, other) {
+        const col = other === "to" ? citesT.from : citesT.to;
+        const rows = await this.db
+            .select({
+            id: citesT[other],
+            type: recordsT.type,
+            title: recordsT.title,
+            status: recordsT.status,
+        })
+            .from(citesT)
+            .leftJoin(recordsT, and(eq(recordsT.repo, citesT.repo), eq(recordsT.id, citesT[other])))
+            .where(and(eq(citesT.repo, repo), eq(col, id)));
+        return rows.map((r) => ({
+            id: r.id,
+            type: r.type,
+            title: r.title,
+            status: r.status ?? "missing",
+        }));
+    }
+    async find(repo, f = {}) {
+        await this.init();
+        const where = [];
+        if (repo)
+            where.push(eq(recordsT.repo, repo));
+        if (f.type)
+            where.push(eq(recordsT.type, f.type));
+        if (f.topic)
+            where.push(eq(recordsT.topic, f.topic));
+        if (f.status)
+            where.push(eq(recordsT.status, f.status));
+        for (const w of (f.q ?? "").split(/\s+/).filter(Boolean)) {
+            const like = `%${w.replace(/[%_\\]/g, (c) => `\\${c}`)}%`;
+            where.push(or(ilike(recordsT.title, like), ilike(recordsT.body, like), ilike(recordsT.id, like)));
+        }
+        return this.db
+            .select()
+            .from(recordsT)
+            .where(where.length ? and(...where) : undefined)
+            .orderBy(desc(recordsT.updated))
+            .limit(f.limit ?? 50);
+    }
+    /** Live records whose evidence is missing, retired, or changed after them. */
+    async stale(repo) {
+        await this.init();
+        const res = await this.db.execute(sql `
+      select r.id, r.type, r.title, c."to" as cites, t.status as cited_status,
+        case when t.id is null then 'missing' when t.status = 'retired' then 'retired' else 'changed' end as why
+      from knowledge_cites c
+      join knowledge_records r on r.repo = c.repo and r.id = c."from"
+      left join knowledge_records t on t.repo = c.repo and t.id = c."to"
+      where c.repo = ${repo} and r.status = 'live'
+        and (t.id is null or t.status = 'retired' or t.updated > r.updated)
+      order by r.id`);
+        return rowsOf(res);
+    }
+}
+function toRow(repo, path, fm, body) {
+    return {
+        repo,
+        id: fm.id,
+        type: fm.type,
+        title: fm.title,
+        status: fm.status,
+        version: fm.version,
+        by: fm.by,
+        why: fm.why,
+        path,
+        topic: fm.type === "rule" ? fm.topic : null,
+        source: fm.type === "finding" ? fm.source : null,
+        body,
+        data: fm,
+        created: fm.created,
+        updated: fm.updated,
+    };
+}
+// PGlite answers { rows }, postgres-js an array
+const rowsOf = (r) => Array.isArray(r) ? r : (r.rows ?? []);
+/** PGlite in a folder (a checkout's own), or Postgres when a URL is given. */
+export async function openIndex(opts) {
+    if (opts.url) {
+        const { default: postgres } = await import("postgres");
+        const { drizzle } = await import("drizzle-orm/postgres-js");
+        const client = postgres(opts.url, { max: 2, onnotice: () => { } });
+        return new RecordIndex(drizzle(client), () => client.end());
+    }
+    const { PGlite } = await import("@electric-sql/pglite");
+    const { drizzle } = await import("drizzle-orm/pglite");
+    const client = opts.dir ? new PGlite(opts.dir) : new PGlite();
+    return new RecordIndex(drizzle(client), () => client.close());
+}
+//# sourceMappingURL=record-index.js.map

package/dist/record-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-index.js","sourceRoot":"","sources":["../src/record-index.ts"],"names":[],"mappings":"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"}

package/dist/records.d.ts

@@ -0,0 +1,226 @@
+import { z } from "zod";
+export declare const TYPES: readonly ["source", "finding", "verdict", "rule"];
+export type RecordType = (typeof TYPES)[number];
+export declare const DIRS: Record<RecordType, string>;
+export declare const Id: z.ZodString;
+export declare const SOURCE_KINDS: readonly ["site", "page", "video", "reel", "post", "person", "tool", "doc", "paper", "feed", "repo", "list", "other"];
+export declare const Source: z.ZodObject<{
+    type: z.ZodLiteral<"source">;
+    kind: z.ZodEnum<{
+        site: "site";
+        page: "page";
+        video: "video";
+        reel: "reel";
+        post: "post";
+        person: "person";
+        tool: "tool";
+        doc: "doc";
+        paper: "paper";
+        feed: "feed";
+        repo: "repo";
+        list: "list";
+        other: "other";
+    }>;
+    url: z.ZodOptional<z.ZodURL>;
+    handle: z.ZodOptional<z.ZodString>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    media: z.ZodOptional<z.ZodObject<{
+        sha256: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>;
+export declare const Finding: z.ZodObject<{
+    type: z.ZodLiteral<"finding">;
+    source: z.ZodString;
+    quote: z.ZodString;
+    page: z.ZodOptional<z.ZodURL>;
+    at: z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>;
+    run: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>;
+export declare const Verdict: z.ZodObject<{
+    type: z.ZodLiteral<"verdict">;
+    from: z.ZodEnum<{
+        other: "other";
+        vireo: "vireo";
+        orrery: "orrery";
+        owner: "owner";
+    }>;
+    ref: z.ZodString;
+    score: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>;
+export declare const Rule: z.ZodObject<{
+    type: z.ZodLiteral<"rule">;
+    topic: z.ZodString;
+    order: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>;
+export declare const Frontmatter: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"source">;
+    kind: z.ZodEnum<{
+        site: "site";
+        page: "page";
+        video: "video";
+        reel: "reel";
+        post: "post";
+        person: "person";
+        tool: "tool";
+        doc: "doc";
+        paper: "paper";
+        feed: "feed";
+        repo: "repo";
+        list: "list";
+        other: "other";
+    }>;
+    url: z.ZodOptional<z.ZodURL>;
+    handle: z.ZodOptional<z.ZodString>;
+    priority: z.ZodOptional<z.ZodNumber>;
+    media: z.ZodOptional<z.ZodObject<{
+        sha256: z.ZodString;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"finding">;
+    source: z.ZodString;
+    quote: z.ZodString;
+    page: z.ZodOptional<z.ZodURL>;
+    at: z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>;
+    run: z.ZodOptional<z.ZodString>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"verdict">;
+    from: z.ZodEnum<{
+        other: "other";
+        vireo: "vireo";
+        orrery: "orrery";
+        owner: "owner";
+    }>;
+    ref: z.ZodString;
+    score: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>, z.ZodObject<{
+    type: z.ZodLiteral<"rule">;
+    topic: z.ZodString;
+    order: z.ZodOptional<z.ZodNumber>;
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        live: "live";
+        retired: "retired";
+    }>;
+    version: z.ZodNumber;
+    by: z.ZodString;
+    why: z.ZodString;
+    cites: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    created: z.ZodPreprocess<z.ZodString, unknown>;
+    updated: z.ZodPreprocess<z.ZodString, unknown>;
+}, z.core.$loose>], "type">;
+export type Frontmatter = z.infer<typeof Frontmatter>;
+export interface Doc {
+    fm: Frontmatter;
+    body: string;
+}
+/** Where a record lives in the repo. A rule sits under its topic. */
+export declare function pathOf(fm: Pick<Frontmatter, "type" | "id"> & {
+    topic?: unknown;
+}): string;
+/** The ids a record leans on: its cites, and a finding's source. */
+export declare function edgesOf(fm: Frontmatter): string[];
+export declare function newId(title: string): string;
+export type Parsed = {
+    ok: true;
+    doc: Doc;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parse(text: string): Parsed;
+export declare function serialize(doc: Doc): string;

package/dist/records.js

@@ -0,0 +1,149 @@
+/**
+ * A record: one markdown file, frontmatter + body. Design: wren/designs/2026-11-09-knowledge-repo.md.
+ * Unknown frontmatter keys are kept (never drop data); key order on write is fixed, so diffs stay small.
+ */
+import { randomBytes } from "node:crypto";
+import matter from "gray-matter";
+import { z } from "zod";
+export const TYPES = ["source", "finding", "verdict", "rule"];
+export const DIRS = {
+    source: "sources",
+    finding: "findings",
+    verdict: "verdicts",
+    rule: "rules",
+};
+// readable ids: a source keeps its natural one (youtube-uSTGNHGFOAo); new ones are slug + random tail
+export const Id = z
+    .string()
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/, "id: letters, digits, . _ -");
+// YAML reads a bare timestamp as a Date; every stamp is stored as a full UTC ISO string
+const Stamp = z.preprocess((v) => (v instanceof Date ? v.toISOString() : v), z.string().refine((s) => !Number.isNaN(Date.parse(s)), "not a date"));
+const Text = z.preprocess((v) => (typeof v === "number" ? String(v) : v), z.string());
+const base = {
+    id: Id,
+    title: z.string().min(1),
+    status: z.enum(["live", "retired"]),
+    version: z.number().int().positive(),
+    by: z.string().min(1),
+    why: z.string().min(1),
+    cites: z.array(Id).default([]),
+    tags: z.array(z.string()).default([]),
+    created: Stamp,
+    updated: Stamp,
+};
+export const SOURCE_KINDS = [
+    "site",
+    "page",
+    "video",
+    "reel",
+    "post",
+    "person",
+    "tool",
+    "doc",
+    "paper",
+    "feed",
+    "repo",
+    "list",
+    "other",
+];
+export const Source = z.looseObject({
+    ...base,
+    type: z.literal("source"),
+    kind: z.enum(SOURCE_KINDS),
+    url: z.url().optional(),
+    handle: z.string().optional(),
+    // 1 (low) to 9: how much a build leans on it
+    priority: z.number().int().min(1).max(9).optional(),
+    // a file in the media bucket, by content hash
+    media: z.object({ sha256: z.string().regex(/^[0-9a-f]{64}$/), type: z.string() }).optional(),
+});
+export const Finding = z.looseObject({
+    ...base,
+    type: z.literal("finding"),
+    source: Id,
+    quote: z.string().min(1),
+    page: z.url().optional(),
+    // where in the source: a time (0:16), a page, a slide
+    at: Text.optional(),
+    run: z.string().optional(),
+});
+export const Verdict = z.looseObject({
+    ...base,
+    type: z.literal("verdict"),
+    from: z.enum(["vireo", "orrery", "owner", "other"]),
+    // the producer's own handle: a Vireo batch ref (hero:3), a lane id
+    ref: z.string().min(1),
+    score: z.number().optional(),
+});
+export const Rule = z.looseObject({
+    ...base,
+    type: z.literal("rule"),
+    topic: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "topic: lowercase slug"),
+    order: z.number().optional(),
+});
+export const Frontmatter = z.discriminatedUnion("type", [Source, Finding, Verdict, Rule]);
+/** Where a record lives in the repo. A rule sits under its topic. */
+export function pathOf(fm) {
+    const dir = DIRS[fm.type];
+    return fm.type === "rule" ? `${dir}/${String(fm.topic)}/${fm.id}.md` : `${dir}/${fm.id}.md`;
+}
+/** The ids a record leans on: its cites, and a finding's source. */
+export function edgesOf(fm) {
+    return [...new Set(fm.type === "finding" ? [...fm.cites, fm.source] : fm.cites)];
+}
+const B32 = "0123456789abcdefghjkmnpqrstvwxyz";
+export function newId(title) {
+    const slug = title
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40)
+        .replace(/-+$/, "");
+    const tail = [...randomBytes(6)].map((b) => B32[b % 32]).join("");
+    return slug ? `${slug}-${tail}` : tail;
+}
+export function parse(text) {
+    let m;
+    try {
+        // options object: gray-matter caches option-less calls by text and hands back one shared object
+        m = matter(text, {});
+    }
+    catch (e) {
+        return { ok: false, error: `frontmatter: ${e.message.split("\n")[0]}` };
+    }
+    const r = Frontmatter.safeParse(m.data);
+    if (!r.success)
+        return {
+            ok: false,
+            error: r.error.issues
+                .map((i) => `${i.path.join(".") || "frontmatter"}: ${i.message}`)
+                .join("; "),
+        };
+    const fm = r.data;
+    fm.created = new Date(fm.created).toISOString();
+    fm.updated = new Date(fm.updated).toISOString();
+    return { ok: true, doc: { fm, body: m.content.replace(/^\n+/, "").replace(/\s+$/, "") } };
+}
+const HEAD = ["id", "type", "title", "status", "version", "by", "why", "cites", "tags"];
+const TAIL = ["created", "updated"];
+export function serialize(doc) {
+    const fm = doc.fm;
+    const out = {};
+    const put = (k) => {
+        const v = fm[k];
+        if (v === undefined || (Array.isArray(v) && v.length === 0))
+            return;
+        out[k] = v;
+    };
+    for (const k of HEAD)
+        put(k);
+    for (const k of Object.keys(fm)
+        .filter((k) => !HEAD.includes(k) && !TAIL.includes(k))
+        .sort())
+        put(k);
+    for (const k of TAIL)
+        put(k);
+    return matter.stringify(doc.body ? `\n${doc.body}\n` : "", out);
+}
+//# sourceMappingURL=records.js.map

package/dist/records.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"records.js","sourceRoot":"","sources":["../src/records.ts"],"names":[],"mappings":"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"}