@wxxb789/anc 0.0.1

package/src/lib/schema.js

@@ -0,0 +1,578 @@
+/**
+ * Authoritative schema for the generated public content artifact.
+ *
+ * The artifact is produced from the user's notes by the shipped producer, or by
+ * this repository's fixture build, and is never hand-edited. Validation is
+ * deliberately strict: unknown fields are rejected so a producer change is a
+ * loud build failure rather than a silent privacy leak.
+ */
+import { compareSlugs, isNoteSlug, SLUG_MAX_BYTES } from "./route-path.js";
+export const SCHEMA_VERSION = 1;
+/** Top-level route segments the site owns; a note slug may not collide with them. */
+export const RESERVED_SLUGS = new Set([
+    'notes',
+    'tags',
+    'collections',
+    'recent',
+    'graph',
+    'search',
+    'about',
+    'privacy',
+    // Where a link to a withheld note lands. Reserved for a reason the others are
+    // not: `markdown.ts`'s `INTERNAL_HREF` rewrites every single-segment
+    // `/<slug>/` href through `routeForSlug`, so a note published under this slug
+    // would silently capture every withheld link on the site and send readers to
+    // itself. See `WITHHELD_ROUTE` in `src/lib/route-path.ts`, and the gate in
+    // `tests/route-model.test.ts` that holds the mechanism rather than the
+    // membership.
+    'private',
+    '404',
+    'rss',
+    'sitemap',
+    'pagefind',
+    'data',
+    'wasm',
+]);
+/**
+ * A note slug: `isNoteSlug` from `route-path.ts`, the one definition every
+ * consumer shares.
+ *
+ * Unicode letters, numbers, and marks in hyphen-separated runs — `日记-今天`,
+ * `projects-观点`, `three-laws` — lowercase, NFC, with no invisible code point,
+ * no leading, trailing, or doubled hyphen, and at most `SLUG_MAX_BYTES` UTF-8
+ * bytes. The doubled-hyphen rule exists because a slug and a collection are used
+ * *verbatim* as public route segments, and `src/lib/routes.ts` rejects a doubled
+ * separator in any route key. The two rules are asserted to agree in
+ * `tests/route-model.test.ts`.
+ */
+export function isSlug(value) {
+    return isNoteSlug(value);
+}
+/** ISO 8601 calendar date, optionally with a time and explicit offset. */
+const DATE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))?$/;
+/** BCP 47 shape, e.g. `en`, `zh-CN`, `zh-Hans-CN`. */
+const LANGUAGE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+export function isLanguageTag(value) {
+    return LANGUAGE.test(value);
+}
+/** Joins emoji sequences into one glyph, so it is allowed inside a tag or alias. */
+const ZERO_WIDTH_JOINER = String.fromCharCode(0x200d);
+export function isSafeTagOrAlias(value) {
+    return !value.includes('/') && !/[\p{Cc}\p{Cf}]/u.test(value.replaceAll(ZERO_WIDTH_JOINER, ''));
+}
+const STATUS_VALUES = new Set(['published', 'tombstone']);
+const REQUIRED_STRINGS = ['slug', 'title', 'excerpt', 'markdown'];
+const OPTIONAL_FIELDS = [
+    'public_id',
+    'created',
+    'updated',
+    'language',
+    'tags',
+    'collection',
+    'status',
+    'aliases',
+    'description',
+    // Relationship authorities are **not** serialized in the packaged artifact:
+    // the snapshot is the public relation model, and the renderer reads it. They
+    // remain accepted here because this repository's own producer handoff and its
+    // committed fixture corpora still carry them, and because a mixed artifact is
+    // a producer defect worth naming.
+    'outgoing',
+    'backlinks',
+];
+const KNOWN_FIELDS = new Set([
+    ...REQUIRED_STRINGS,
+    ...OPTIONAL_FIELDS,
+]);
+/**
+ * Size ceilings, stated per field.
+ *
+ * Without these the contract bounds nothing: a 3 MB `markdown` body and 5,000
+ * tags both pass, and 5,000 tags on one entry is 5,000 public routes. A limit
+ * that fails validation is a message naming the field; the same input without
+ * one is a build that either takes minutes or emits a route map the host
+ * rejects.
+ *
+ * Lengths are counted in UTF-16 code units, which is what `String.length`
+ * returns. The number is a size ceiling, not a grapheme count, so counting
+ * astral characters as two is the honest direction: an emoji really does cost
+ * twice a Latin letter to store and to serve.
+ *
+ * Each ceiling is set an order of magnitude above anything the corpus plausibly
+ * produces, so it catches a runaway producer rather than constraining an author.
+ */
+const STRING_LIMITS = {
+    // A path segment. The binding bound is `SLUG_MAX_BYTES` (UTF-8 bytes, a
+    // filesystem name limit), enforced by `isSlug`; this UTF-16 ceiling is the
+    // same number and can never be the tighter of the two.
+    slug: SLUG_MAX_BYTES,
+    // A `<title>`, a card heading, and a search result. Search engines truncate a
+    // title well below this.
+    title: 300,
+    // The `<meta name="description">`, the card body, and the hover preview.
+    excerpt: 1000,
+    description: 1000,
+    // Requirements section 18 warns above 250 KB of uncompressed article HTML,
+    // and rendering Markdown only adds markup, so the source is bounded below it.
+    markdown: 200_000,
+    // An opaque public identifier, not prose.
+    public_id: 128,
+    // BCP 47 language tags are capped at 35 characters by the registry itself.
+    language: 35,
+    collection: 128,
+};
+/** Array ceilings: how many members, and how long each member may be. */
+const ARRAY_LIMITS = {
+    // Every tag is a public route, so an unbounded tag list is an unbounded page
+    // count. A note carrying more than this is a classification failure, not a
+    // note. There is no matching ceiling on the *corpus* — see the note below
+    // on why the entry limit was removed.
+    tags: { items: 50, itemChars: 128 },
+    // Aliases are bounded public display/search/preview metadata.
+    aliases: { items: 50, itemChars: 300 },
+    // `outgoing` and `backlinks` deliberately have no count ceiling. The old 500
+    // was a serialized-array limit, and the SQLite projection is the relationship
+    // authority now: a hub with thousands of backlinks must stay fully reachable,
+    // and a graph drawing bound must never reject a DB fact. A producer defect is
+    // caught by the edge's own resolution and foreign-key checks instead.
+};
+/** Size ceilings for a field, exposed so a consumer can state the same number. */
+export const FIELD_LIMITS = { strings: STRING_LIMITS, arrays: ARRAY_LIMITS };
+/**
+ * **There is no ceiling on how many entries an artifact may carry, and the
+ * removal of one is the deliberate part.**
+ *
+ * A `MAX_ENTRIES = 900` lived here and refused a corpus past it. Measured
+ * against the shipped binary, a generated repository of 1,000 notes failed the
+ * build outright: `entries: has 957 entries, over the limit of 900`. An ordinary
+ * Obsidian vault passes 900 notes in a year or two, so the tool refused the
+ * corpus it exists to publish.
+ *
+ * Both premises the number rested on had already stopped being true, and its own
+ * comment said so:
+ *
+ * - *"An artifact past this is an exporter fault — the allowlist is
+ *   hand-curated."* There is no allowlist. Under default-publish every Markdown
+ *   file in a stranger's repository is an entry, and a stranger does not curate
+ *   them.
+ * - *"900 rather than a round 1,000 to leave headroom under Cloudflare Pages'
+ *   ceiling of 2,000 static redirect rules … TK-12 deleted those rules, so today
+ *   the ceiling is not binding."* The host limit it protected is not reached,
+ *   because `REDIRECT_RULES` is a hand-written literal that cannot grow with the
+ *   corpus.
+ *
+ * So it was retained on a hypothetical — that a future rename might make rules
+ * derived again — while the fault it named could not occur. A cap kept for a
+ * mechanism that does not exist is a cap that fails real users to protect a
+ * theoretical one.
+ *
+ * **What is lost, stated plainly.** A producer that runs away now exhausts
+ * memory instead of failing with a message. That trade was made knowingly: the
+ * limit did not distinguish a runaway producer from an ordinary vault, so it
+ * caught the second far more often than the first. If a guard is wanted later it
+ * should be an order of magnitude above any real corpus and named for what it
+ * catches, rather than a number chosen for a host constraint that no longer
+ * applies.
+ *
+ * Two comments elsewhere quote this ceiling as the bound on their own timings —
+ * `src/lib/relations.ts` and `src/lib/graph.ts`. Their measurements stand as
+ * measurements *at 900 entries*; they no longer describe the largest corpus this
+ * tool accepts, and both say so.
+ */
+function checkLimits(value, label, issues) {
+    for (const [field, max] of Object.entries(STRING_LIMITS)) {
+        const item = value[field];
+        if (typeof item === 'string' && item.length > max) {
+            issues.push(`${label}.${field}: is ${item.length} characters, over the ${max} character limit`);
+        }
+    }
+    for (const [field, { items, itemChars }] of Object.entries(ARRAY_LIMITS)) {
+        const list = value[field];
+        if (!Array.isArray(list))
+            continue;
+        if (list.length > items) {
+            issues.push(`${label}.${field}: has ${list.length} entries, over the limit of ${items}`);
+        }
+        if (itemChars === undefined)
+            continue;
+        for (const [position, member] of list.entries()) {
+            if (typeof member === 'string' && member.length > itemChars) {
+                issues.push(`${label}.${field}[${position}]: is ${member.length} characters, ` +
+                    `over the ${itemChars} character limit`);
+            }
+        }
+    }
+}
+export function contentLimitIssues(value, label) {
+    const issues = [];
+    checkLimits(value, label, issues);
+    return issues;
+}
+/**
+ * Markers that must never reach a public artifact. Scanned against each entry's
+ * string values so that no field, present or future, can smuggle one through.
+ *
+ * These are deliberately NOT matched against a whitespace-stripped form: doing so
+ * would join unrelated lines and turn prose such as "Option A:" above "/usr/bin"
+ * into an apparent drive path.
+ *
+ * **`[[` used to be on this list and is not, and the removal is TK-27's.** It was
+ * never a privacy rule — `[[` discloses nothing — it was a proxy for "the
+ * producer forgot to resolve something", and it was safe only while the producer
+ * resolved every wikilink against a closed allowlist. Under default-publish the
+ * proxy is false in both directions: a link that resolves to nothing now
+ * degrades to text by design, and a note *documenting* wikilink syntax inside a
+ * code fence is content that must publish. Measured on the shipped binary, a
+ * two-note corpus containing one fenced `[[documented syntax]]` failed the build
+ * with "forbidden unresolved [[wikilink]]".
+ *
+ * The invariant that replaces it lives where the information is, in
+ * `scripts/resolve-links.ts`: every wikilink *node* the parser found has a
+ * recorded resolution, so a `[[` surviving in `markdown` is by construction
+ * inside a fence, inside inline code, or escaped. The residue scan over `dist/`
+ * keeps a narrowed form of the old rule, because there a stray `[[` outside a
+ * code region means the degradation itself failed — a producer defect rather
+ * than a user's.
+ */
+const STRUCTURAL_MARKERS = [
+    [/msw\//i, 'private "msw/" path marker'],
+    [/(?<![A-Za-z])[A-Za-z]:[\\/]/, 'absolute local path'],
+];
+/**
+ * Schemes a browser resolves after discarding whitespace anywhere in the URL, so
+ * these are matched against a whitespace-stripped form too. Mirrors the
+ * producer's own rule. `file:` carries a lookbehind so that ordinary words
+ * ending in "file" ("profile:", "makefile:") followed by "//" stay readable.
+ */
+const UNSAFE_SCHEMES = [
+    [/javascript:/i, 'javascript: URL'],
+    [/vbscript:/i, 'vbscript: URL'],
+    [/(?<![A-Za-z])file:\/\//i, 'file:// URL'],
+];
+/**
+ * A `data:` URL whose media type is not an allowlisted base64 raster image.
+ *
+ * Anchored on the `,` that separates a data URL's media type from its payload,
+ * so prose such as "Response data: see below" is not mistaken for one. The media
+ * type is optional because `data:,` and `data:;base64,` are both legal and both
+ * default to `text/plain`, and it is matched as "anything up to the comma" so a
+ * parameter or a wildcard type cannot carry a payload past the gate.
+ *
+ * Interior whitespace is excluded: a media type containing a space does not
+ * parse, so `data:text /html,x` degrades to `text/plain` in a browser, and
+ * excluding it is what keeps a sentence like "Sample data: see docs/guide, then
+ * run it" readable. Whitespace immediately after `data:` or before the comma IS
+ * stripped by the browser, so `stripDataUrlPadding` removes it before this runs.
+ */
+const DISALLOWED_DATA_URI = [
+    /data:(?!image\/(?:png|jpe?g|gif|webp|avif);base64,)(?:,|[^,\s]*(?:\/|;base64)[^,\s]*,)/i,
+    'non-image data: URL',
+];
+/**
+ * Drop the whitespace a browser trims from a data URL's media type (fetch spec:
+ * the media type is trimmed before parsing), so `data: text/html,` and
+ * `data:text/html ,` are judged as the `text/html` they actually resolve to.
+ */
+function stripDataUrlPadding(text) {
+    return text.replace(/(data:)[ \t]+/gi, '$1').replace(/[ \t]+,/g, ',');
+}
+/**
+ * Characters a URL parser discards from anywhere in a URL (WHATWG URL: tab, LF,
+ * CR) plus the invisible format characters that could hide inside a marker. A
+ * literal space is deliberately NOT removed — browsers do not strip it, so
+ * removing it here would fuse ordinary prose into an apparent URL.
+ */
+const URL_IGNORED = /[\t\n\r\p{Cf}]+/gu;
+/** Invisible characters only: safe to remove before looking for a literal marker. */
+const INVISIBLE = /\p{Cf}+/gu;
+const NAMED_ENTITIES = {
+    amp: '&',
+    apos: "'",
+    colon: ':',
+    gt: '>',
+    lt: '<',
+    newline: '\n',
+    quot: '"',
+    sol: '/',
+    tab: '\t',
+};
+export class ContentValidationError extends Error {
+    issues;
+    constructor(source, issues) {
+        super(`${source}: ${issues.length} content contract violation${issues.length === 1 ? '' : 's'}\n` +
+            issues.map((issue) => `  - ${issue}`).join('\n'));
+        this.name = 'ContentValidationError';
+        this.issues = issues;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Decode the entity forms a browser would resolve inside an attribute value. */
+function decodeEntities(value) {
+    return value.replace(/&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([A-Za-z][A-Za-z0-9]*));?/g, (match, decimal, hex, name) => {
+        const code = decimal !== undefined ? Number(decimal) : hex !== undefined ? parseInt(hex, 16) : NaN;
+        if (Number.isFinite(code))
+            return code <= 0x10ffff ? String.fromCodePoint(code) : match;
+        return (name !== undefined ? NAMED_ENTITIES[name.toLowerCase()] : undefined) ?? match;
+    });
+}
+function scan(text, rules, found) {
+    for (const [pattern, label] of rules)
+        if (pattern.test(text))
+            found.add(label);
+}
+/**
+ * Every string reachable in the entry, so no field can hide a marker in a nested
+ * value. Iterative rather than recursive, and pushing one element at a time
+ * rather than spreading: a deeply nested or very wide artifact must fail
+ * validation with a contract error, not crash the build.
+ */
+function* strings(value) {
+    const stack = [value];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (typeof current === 'string')
+            yield current;
+        else if (Array.isArray(current))
+            for (const item of current)
+                stack.push(item);
+        else if (typeof current === 'object' && current !== null) {
+            for (const [key, item] of Object.entries(current)) {
+                yield key;
+                stack.push(item);
+            }
+        }
+    }
+}
+function checkPrivacy(entry, label, issues) {
+    const found = new Set();
+    // Scan the parsed string values, not the JSON encoding of the entry: in JSON
+    // text a newline is the two characters "\" + "n", which would make ordinary
+    // prose such as "Option A:\n- foo" look like the drive path "A:\".
+    for (const value of strings(entry)) {
+        const decoded = decodeEntities(value);
+        // Structural markers get the invisible characters removed, so `msw<ZWJ>/x`
+        // cannot hide a private path that a browser would still render as `msw/x`.
+        // They do NOT get line breaks removed: joining lines would turn prose such
+        // as "Option A:" above "/usr/bin" into an apparent drive path.
+        const visible = decoded.replace(INVISIBLE, '');
+        // Scheme rules additionally drop the tab/CR/LF a URL parser ignores, so
+        // `java\tscript:` inside one URL is caught. This mirrors the producer.
+        const compact = decoded.replace(URL_IGNORED, '');
+        for (const text of [value, decoded, visible])
+            scan(text, STRUCTURAL_MARKERS, found);
+        for (const text of [value, decoded, compact]) {
+            scan(text, UNSAFE_SCHEMES, found);
+            scan(stripDataUrlPadding(text), [DISALLOWED_DATA_URI], found);
+        }
+    }
+    for (const marker of [...found].sort())
+        issues.push(`${label}: forbidden ${marker} in serialized content`);
+}
+export function contentPrivacyIssues(value, label) {
+    const issues = [];
+    checkPrivacy(value, label, issues);
+    return issues;
+}
+function checkStringArray(value, label, issues, options) {
+    if (!Array.isArray(value)) {
+        issues.push(`${label}: must be an array of strings`);
+        return false;
+    }
+    const clean = value.filter((item, index) => {
+        const ok = typeof item === 'string' && item.trim() !== '' && item === item.trim();
+        if (!ok)
+            issues.push(`${label}[${index}]: must be a non-empty string without surrounding whitespace`);
+        return ok;
+    });
+    if (clean.length !== value.length)
+        return false;
+    if (new Set(clean).size !== clean.length)
+        issues.push(`${label}: must not contain duplicates`);
+    // Slug lists are in canonical slug order (code points, the order SQLite's
+    // BINARY collation uses), not JavaScript's UTF-16 `<`; see `compareSlugs`.
+    if (options.sorted && clean.some((item, index) => index > 0 && compareSlugs(clean[index - 1], item) > 0)) {
+        issues.push(`${label}: must be sorted in ascending order`);
+    }
+    return true;
+}
+function checkEntry(value, index, issues) {
+    if (!isPlainObject(value)) {
+        issues.push(`entries[${index}]: must be an object`);
+        return undefined;
+    }
+    const slug = value['slug'];
+    const label = typeof slug === 'string' ? `entries[${index}] (slug "${slug}")` : `entries[${index}]`;
+    const before = issues.length;
+    for (const field of Object.keys(value)) {
+        if (!KNOWN_FIELDS.has(field))
+            issues.push(`${label}.${field}: unknown field is not allowed`);
+    }
+    for (const field of REQUIRED_STRINGS) {
+        const item = value[field];
+        if (typeof item !== 'string')
+            issues.push(`${label}.${field}: is required and must be a string`);
+        else if (field !== 'excerpt' && item.trim() === '')
+            issues.push(`${label}.${field}: must not be empty`);
+    }
+    if (typeof slug === 'string') {
+        if (!isSlug(slug)) {
+            issues.push(`${label}.slug: must be lowercase letters, digits, or marks in single-hyphen runs, ` +
+                `NFC, at most ${SLUG_MAX_BYTES} UTF-8 bytes`);
+        }
+        else if (RESERVED_SLUGS.has(slug)) {
+            issues.push(`${label}.slug: collides with reserved route segment "${slug}"`);
+        }
+    }
+    for (const field of ['outgoing', 'backlinks']) {
+        const item = value[field];
+        if (item === undefined)
+            continue;
+        checkStringArray(item, `${label}.${field}`, issues, { sorted: true });
+    }
+    for (const field of ['public_id', 'collection', 'description']) {
+        const item = value[field];
+        if (item !== undefined && (typeof item !== 'string' || item.trim() === '')) {
+            issues.push(`${label}.${field}: must be a non-empty string when present`);
+        }
+    }
+    if (typeof value['collection'] === 'string' && !isSlug(value['collection'])) {
+        issues.push(`${label}.collection: must be lowercase letters, digits, or marks in single-hyphen runs, ` +
+            `NFC, at most ${SLUG_MAX_BYTES} UTF-8 bytes`);
+    }
+    for (const field of ['created', 'updated']) {
+        const item = value[field];
+        if (item !== undefined && (typeof item !== 'string' || !DATE.test(item) || Number.isNaN(Date.parse(item)))) {
+            issues.push(`${label}.${field}: must be an ISO 8601 date when present`);
+        }
+    }
+    const language = value['language'];
+    if (language !== undefined && (typeof language !== 'string' || !isLanguageTag(language))) {
+        issues.push(`${label}.language: must be a BCP 47 language tag when present`);
+    }
+    const status = value['status'];
+    if (status !== undefined && (typeof status !== 'string' || !STATUS_VALUES.has(status))) {
+        issues.push(`${label}.status: must be one of ${[...STATUS_VALUES].join(', ')} when present`);
+    }
+    // Tags become `/tags/<tag>/` route keys; aliases enter display, search, and
+    // preview payloads but deliberately not link resolution. A "/" would break
+    // tag routing and could carry a private path fragment in either field; a control
+    // or format character (bidi overrides, soft hyphens) could disguise either.
+    // U+200D is exempt: it joins emoji sequences such as a person-at-keyboard glyph.
+    for (const field of ['tags', 'aliases']) {
+        const item = value[field];
+        if (item === undefined)
+            continue;
+        if (checkStringArray(item, `${label}.${field}`, issues, { sorted: false })) {
+            for (const [position, member] of item.entries()) {
+                if (!isSafeTagOrAlias(member)) {
+                    issues.push(`${label}.${field}[${position}]: must not contain "/" or a control character`);
+                }
+            }
+        }
+    }
+    // Size before content, and an oversized entry stops here: a 3 MB body is
+    // rejected on its length rather than scanned four times over first, which is
+    // what makes "a contract error, not a slow build" true rather than
+    // aspirational. Only a *size* issue short-circuits — an entry with an unknown
+    // field or a bad slug is still privacy-scanned, so no violation goes
+    // unreported for an entry that would otherwise have been merely malformed.
+    const beforeLimits = issues.length;
+    issues.push(...contentLimitIssues(value, label));
+    if (issues.length !== beforeLimits)
+        return undefined;
+    issues.push(...contentPrivacyIssues(value, label));
+    return issues.length === before ? value : undefined;
+}
+function checkCorpus(entries, issues, edges) {
+    const bySlug = new Map();
+    for (const entry of entries) {
+        if (bySlug.has(entry.slug))
+            issues.push(`entries: duplicate slug "${entry.slug}"`);
+        else
+            bySlug.set(entry.slug, entry);
+    }
+    // No alias is checked across entries. `docs/core-design/content-semantics.md`
+    // owns the rule: aliases are "not alternate resolver targets, routes, globally
+    // unique names, or graph nodes", and "the same alias may belong to different
+    // notes" — so a repeated alias, or an alias that equals another note's slug,
+    // is metadata, not a conflict. The schema still enforces per-note uniqueness
+    // in the SQLite projection's `(node_id, alias)` key.
+    if (!edges)
+        return;
+    const expectedBacklinks = new Map(entries.map((entry) => [entry.slug, []]));
+    for (const entry of entries) {
+        const label = `entries (slug "${entry.slug}")`;
+        for (const target of entry.outgoing) {
+            if (target === entry.slug)
+                issues.push(`${label}.outgoing: must not link to itself`);
+            else if (!bySlug.has(target))
+                issues.push(`${label}.outgoing: "${target}" does not resolve to a published entry`);
+            else
+                expectedBacklinks.get(target)?.push(entry.slug);
+        }
+        for (const source of entry.backlinks) {
+            if (source === entry.slug)
+                issues.push(`${label}.backlinks: must not link to itself`);
+            else if (!bySlug.has(source))
+                issues.push(`${label}.backlinks: "${source}" does not resolve to a published entry`);
+        }
+    }
+    for (const entry of entries) {
+        const expected = (expectedBacklinks.get(entry.slug) ?? []).sort(compareSlugs);
+        const actual = [...entry.backlinks].sort(compareSlugs);
+        if (expected.length !== actual.length || expected.some((slug, index) => slug !== actual[index])) {
+            issues.push(`entries (slug "${entry.slug}").backlinks: must be the exact inverse of outgoing links ` +
+                `(expected [${expected.join(', ')}], got [${entry.backlinks.join(', ')}])`);
+        }
+    }
+}
+/**
+ * Validate a parsed content artifact.
+ *
+ * @throws {ContentValidationError} listing every violation, each naming the
+ * offending entry and field.
+ */
+export function validateArtifact(data, source = 'content artifact') {
+    const issues = [];
+    if (!isPlainObject(data))
+        throw new ContentValidationError(source, ['artifact: must be an object']);
+    for (const field of Object.keys(data)) {
+        if (field !== 'version' && field !== 'entries')
+            issues.push(`${field}: unknown field is not allowed`);
+    }
+    if (data['version'] !== SCHEMA_VERSION) {
+        issues.push(`version: must be ${SCHEMA_VERSION}, got ${JSON.stringify(data['version'])}`);
+    }
+    const rawEntries = data['entries'];
+    if (!Array.isArray(rawEntries))
+        issues.push('entries: must be an array');
+    else {
+        const valid = [];
+        for (const [index, entry] of rawEntries.entries()) {
+            const checked = checkEntry(entry, index, issues);
+            if (checked)
+                valid.push(checked);
+        }
+        const declared = rawEntries.map((entry) => isPlainObject(entry) && 'outgoing' in entry && 'backlinks' in entry);
+        const all = declared.every(Boolean);
+        const none = declared.every((value) => !value);
+        if (!all && !none) {
+            issues.push('entries: outgoing/backlinks must be declared on every entry or on none of them');
+        }
+        if (valid.length === rawEntries.length && (all || none))
+            checkCorpus(valid, issues, all);
+    }
+    if (issues.length > 0)
+        throw new ContentValidationError(source, issues);
+    const artifact = data;
+    // An artifact with no serialized relation authorities is the packaged target:
+    // the snapshot is the public relation model, so the in-memory entries start
+    // with empty lists and the build hydrates them from the finalized DB.
+    for (const entry of artifact.entries) {
+        entry.outgoing ??= [];
+        entry.backlinks ??= [];
+    }
+    return artifact;
+}