@mat3ra/esse 2026.8.18-2 → 2026.8.25-1

package/README.md

@@ -8,7 +8,13 @@ Essential Source of Schemas and Examples (ESSE) contains data format definitions
 
 Although the schemas are used to facilitate the operations of [mat3ra.com](https://mat3ra.com), they are designed to be generic and can be used in other applications. The open-source packages developed by Mat3ra.com use the schemas available in this repository.
 
-The latest variants of schemas and examples are available at [schemas.mat3ra.com](https://schemas.mat3ra.com/).
+The latest variants of schemas and examples are available at [schemas.mat3ra.com](https://schemas.mat3ra.com/), which has three surfaces:
+
+- **[Documentation](https://schemas.mat3ra.com/docs/)** — how ESSE is put together and why: the schema layering, entity anatomy, categorization, conventions and the build pipeline. Start here if you are new.
+- **[Explorer](https://schemas.mat3ra.com/)** — a file browser over every resolved schema and example.
+- **[Entity Map](https://schemas.mat3ra.com/map/)** — an interactive map of all schemas and the references between them, laid out by architectural layer: primitives at the centre, root entities around them, catalogues on the rim. Search for a schema, fly to it, and follow what it extends, contains and is used by.
+
+The map is built from `graph.json`, an extracted reference graph that is also published at [schemas.mat3ra.com/graph.json](https://schemas.mat3ra.com/graph.json) and doubles as a lint over the corpus.
 
 ESSE has a dual-nature as both a Python and a Node.js package.
 
@@ -110,7 +116,7 @@ console.log(result); // {"a": "x", "b": 1}
 
 ## 3. Directory Structure
 
-ESSE contains 3 main directories, [schema](schema), [example](example) and [src](src) outlined below.
+ESSE contains 3 main directories, [schema](schema), [example](example) and [src](src) outlined below, plus [docs](docs) (documentation sources) and [plan](plan) (design documents).
 
 ### 3.1. Schema
 
@@ -130,6 +136,14 @@ This directory contains the examples formed according to the schemas and impleme
 
 This directory contains Python and Javascript interfaces implementing the functionality to access and validate schemas and examples.
 
+### 3.4. docs
+
+Markdown sources for the [concept documentation](https://schemas.mat3ra.com/docs/), rendered to HTML at deploy time. Pages may embed generated fragments (`<!-- generated:name -->`) that are expanded from the entity graph, so counts and relationship listings cannot drift from the schemas.
+
+### 3.5. plan
+
+Design documents, filed by status (`upcoming/`, `review/`, `implemented/`, `context/`) per the convention in [mat3ra/agents](https://github.com/mat3ra/agents/blob/main/AGENTS.md). See [plan/README.md](plan/README.md).
+
 ## 4. Conventions
 
 ### 4.1. Generative vs Non-generative keys
@@ -146,7 +160,7 @@ The following outlines the development process workflow:
 2. Edit code and commit changes.
 3. Pre commit is used to regenerate the modules.
 4. Push the changes to GitHub.
-5. GH workflow is used to generate the fully resolved file (without "$ref"s and "$allOf" etc.) and examples and publish them to [schemas.mat3ra.com](http://schemas.mat3ra.com/).
+5. GH workflow is used to generate the fully resolved file (without "$ref"s and "$allOf" etc.) and examples, render the documentation and the Entity Map, and publish them to [schemas.mat3ra.com](http://schemas.mat3ra.com/). The site is assembled in a gitignored `site/` staging directory; internal links are checked before it deploys.
 6. Publish the new version of the package to PyPI and npm.
 
 The [pre-commit](.husky/pre-commit) is using both JS and PY runtime(s) to regenerate the schemas and examples.
@@ -197,6 +211,8 @@ Other suggestions:
 - Use unique IDs for schemas
 - Do not use circular references in the schemas, instead leave the type as object and add explanation to description.
 
+The schema lint (`npm run lint-entity-graph`, also part of `npm test`) enforces both of the above along with `$id` conventions, JSON-pointer targets and manifest references. [Contributing a schema](https://schemas.mat3ra.com/docs/contributing-a-schema.html) walks through adding one end to end.
+
 ## Links
 
 [^1]: [Data-centric online ecosystem for digital materials science](https://arxiv.org/pdf/1902.10838.pdf)

package/dist/js/scripts/buildDocsPages.d.ts

@@ -0,0 +1,19 @@
+import { type EntityGraph } from "./buildEntityGraph";
+export interface DocsPage {
+    slug: string;
+    title: string;
+    order: number;
+    summary: string;
+    body: string;
+}
+interface FrontMatter {
+    [key: string]: string;
+}
+/** Splits a leading `---` block off the document. Enough for title/order/summary. */
+export declare function parseFrontMatter(source: string): {
+    data: FrontMatter;
+    body: string;
+};
+export declare function expandFragments(body: string, graph: EntityGraph): string;
+export declare function buildDocsPages(outputDir: string): DocsPage[];
+export {};

package/dist/js/scripts/buildDocsPages.js

@@ -0,0 +1,419 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFrontMatter = parseFrontMatter;
+exports.expandFragments = expandFragments;
+exports.buildDocsPages = buildDocsPages;
+/**
+ * Renders the concept documentation in `docs/` to static HTML for the site.
+ *
+ * Deliberately small: `marked` plus the site's own chrome, no static site generator.
+ * Ten pages do not justify a toolchain, and the repository's web surface is otherwise
+ * build-free.
+ *
+ * Pages may embed generated fragments (`<!-- generated:name -->`), which are expanded from
+ * the entity graph at build time. Prose stays prose in git while the published pages carry
+ * live numbers, so the documentation cannot quietly drift from the schemas it describes.
+ */
+const fs_1 = __importDefault(require("fs"));
+const marked_1 = require("marked");
+const path_1 = __importDefault(require("path"));
+const buildEntityGraph_1 = require("./buildEntityGraph");
+const REPOSITORY_ROOT = path_1.default.resolve(__dirname, "../../../");
+const DOCS_SOURCE_DIR = path_1.default.join(REPOSITORY_ROOT, "docs");
+/** Splits a leading `---` block off the document. Enough for title/order/summary. */
+function parseFrontMatter(source) {
+    const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+    if (!match)
+        return { data: {}, body: source };
+    const data = {};
+    match[1].split(/\r?\n/).forEach((line) => {
+        const separator = line.indexOf(":");
+        if (separator === -1)
+            return;
+        data[line.slice(0, separator).trim()] = line
+            .slice(separator + 1)
+            .trim()
+            .replace(/^["']|["']$/g, "");
+    });
+    return { data, body: source.slice(match[0].length) };
+}
+// ── Generated fragments ───────────────────────────────────────────────────────
+function mapLink(id) {
+    return `[\`${id}\`](../map/#/entity/${encodeURIComponent(id)})`;
+}
+function table(headers, rows) {
+    return [
+        `| ${headers.join(" | ")} |`,
+        `| ${headers.map(() => "---").join(" | ")} |`,
+        ...rows.map((row) => `| ${row.join(" | ")} |`),
+    ].join("\n");
+}
+function relationshipFragment(graph, id) {
+    const node = graph.nodes.find((candidate) => candidate.id === id);
+    if (!node)
+        throw new Error(`entity-relationships fragment references unknown schema "${id}"`);
+    const describe = (kind, direction) => graph.edges
+        .filter((edge) => edge.kind === kind && edge[direction === "target" ? "source" : "target"] === id)
+        .map((edge) => {
+        const other = direction === "target" ? edge.target : edge.source;
+        return `${mapLink(other)}${edge.label ? ` \`${edge.label}\`` : ""}`;
+    });
+    const sections = [];
+    const extendsList = describe("extends", "target");
+    const containsList = describe("contains", "target");
+    const variantList = describe("variant", "target");
+    const usedBy = graph.edges
+        .filter((edge) => edge.target === id)
+        .map((edge) => mapLink(edge.source));
+    if (extendsList.length)
+        sections.push(`**Extends** — ${extendsList.join(", ")}`);
+    if (containsList.length)
+        sections.push(`**Contains** — ${containsList.join(", ")}`);
+    if (variantList.length > 0) {
+        sections.push(variantList.length > 12
+            ? `**Variants** — ${variantList.length} schemas, see the map`
+            : `**Variants** — ${variantList.join(", ")}`);
+    }
+    if (usedBy.length) {
+        sections.push(usedBy.length > 12
+            ? `**Used by** — ${usedBy.length} schemas, see the map`
+            : `**Used by** — ${usedBy.join(", ")}`);
+    }
+    return sections.length ? sections.map((line) => `${line}\n`).join("\n") : "_No references._";
+}
+function mixinUsageFragment(graph) {
+    const mixins = new Map();
+    graph.edges
+        .filter((edge) => edge.kind === "extends")
+        .forEach((edge) => {
+        const target = graph.nodes.find((node) => node.id === edge.target);
+        if (!target || (target.layer !== "in-memory-entity" && target.layer !== "system"))
+            return;
+        if (!mixins.has(edge.target))
+            mixins.set(edge.target, []);
+        mixins.get(edge.target).push(edge.source);
+    });
+    const rows = [...mixins.entries()]
+        .sort((a, b) => b[1].length - a[1].length || a[0].localeCompare(b[0]))
+        .slice(0, 15)
+        .map(([mixin, users]) => [mapLink(mixin), String(users.length)]);
+    return table(["Mixin", "Schemas extending it"], rows);
+}
+/**
+ * The corpus categorizes along more than one scheme, and the difference matters when
+ * reading a `*_category` path. This is derived rather than asserted: the tiered
+ * vocabulary is the transitive `extends` closure into `core/reusable/categories`, so
+ * a materials schema that adopted tiers tomorrow would move rows without an edit here.
+ */
+function categorizationSchemesFragment(graph) {
+    const parents = new Map();
+    graph.edges
+        .filter((edge) => edge.kind === "extends")
+        .forEach((edge) => {
+        if (!parents.has(edge.source))
+            parents.set(edge.source, []);
+        parents.get(edge.source).push(edge.target);
+    });
+    const CATEGORIES = "core/reusable/categories";
+    const reachesCategories = (id, seen = new Set()) => {
+        var _a;
+        if (id === CATEGORIES)
+            return true;
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return ((_a = parents.get(id)) !== null && _a !== void 0 ? _a : []).some((parent) => reachesCategories(parent, seen));
+    };
+    const countUnder = (prefix) => graph.nodes.filter((node) => node.id.startsWith(prefix)).length;
+    const carriers = graph.edges
+        .filter((edge) => edge.target === CATEGORIES && edge.kind === "contains")
+        .map((edge) => edge.source)
+        .sort();
+    const domains = ["models-category", "methods-category", "materials-category"];
+    const rows = domains.map((domain) => {
+        const prefix = `${domain}/`;
+        const total = countUnder(prefix);
+        const rest = graph.nodes.filter((node) => node.id.startsWith(prefix) && !reachesCategories(node.id));
+        const tiered = total - rest.length;
+        if (!tiered)
+            return [`\`${domain}\``, String(total), "none — compositional"];
+        // Today the untiered remainder is entirely enum holders; say so only while true.
+        const allEnums = rest.every((node) => /\/enum-options$|\/enums$/.test(node.id));
+        const remainder = rest.length
+            ? ` + ${rest.length} ${allEnums ? "enum holders" : "other"}`
+            : "";
+        return [`\`${domain}\``, String(total), `${tiered} tiered${remainder}`];
+    });
+    rows.push([
+        "`materials-category-components`",
+        String(countUnder("materials-category-components/")),
+        `${countUnder("materials-category-components/entities/")} entities + ${countUnder("materials-category-components/operations/")} operations`,
+    ]);
+    const carrierList = carriers.map(mapLink).join(", ");
+    return `${table(["Category domain", "Schemas", "Scheme"], rows)}
+
+Entities carrying a tiered \`categories\` field: ${carrierList || "_none_"}.`;
+}
+function layerInventoryFragment(graph) {
+    const rows = Object.entries(graph.meta.layerCounts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([layer, count]) => [`\`${layer}\``, String(count)]);
+    return table(["Layer", "Schemas"], rows);
+}
+function hubTableFragment(graph) {
+    const rows = [...graph.nodes]
+        .sort((a, b) => b.inDegree - a.inDegree || a.id.localeCompare(b.id))
+        .slice(0, 10)
+        .map((node) => [mapLink(node.id), String(node.inDegree)]);
+    return table(["Schema", "Referenced by"], rows);
+}
+function expandFragments(body, graph) {
+    return body.replace(/<!--\s*generated:([^\s]+)\s*-->/g, (_match, name) => {
+        const [fragment, argument] = name.split(":");
+        switch (fragment) {
+            case "corpus-totals":
+                return table(["Schemas", "References", "extends", "contains", "variant"], [
+                    [
+                        String(graph.meta.nodeCount),
+                        String(graph.meta.edgeCount),
+                        String(graph.meta.edgeCountsByKind.extends),
+                        String(graph.meta.edgeCountsByKind.contains),
+                        String(graph.meta.edgeCountsByKind.variant),
+                    ],
+                ]);
+            case "layer-inventory":
+                return layerInventoryFragment(graph);
+            case "categorization-schemes":
+                return categorizationSchemesFragment(graph);
+            case "hub-table":
+                return hubTableFragment(graph);
+            case "mixin-usage":
+                return mixinUsageFragment(graph);
+            case "example-coverage":
+                return `${graph.meta.schemasWithExample} of ${graph.meta.nodeCount} schemas (${Math.round((graph.meta.schemasWithExample / graph.meta.nodeCount) * 100)}%) have a mirror example`;
+            case "entity-relationships":
+                return relationshipFragment(graph, argument);
+            default:
+                throw new Error(`Unknown generated fragment "${name}"`);
+        }
+    });
+}
+// ── Rendering ─────────────────────────────────────────────────────────────────
+function escapeHtml(value) {
+    return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function renderPage(page, pages, html) {
+    const nav = pages
+        .map((item) => `<a href="${item.slug}.html"${item.slug === page.slug ? ' class="current"' : ""}>` +
+        `${escapeHtml(item.title)}</a>`)
+        .join("\n            ");
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${escapeHtml(page.title)} — ESSE</title>
+    <meta name="description" content="${escapeHtml(page.summary)}">
+    <link rel="stylesheet" href="docs.css">
+</head>
+<body>
+<div id="titlebar">
+    <span class="app-name">ESSE</span>
+    <nav id="surfaces">
+        <a href="index.html" class="current">Docs</a>
+        <a href="../index.html">Explorer</a>
+        <a href="../map/index.html">Map</a>
+    </nav>
+</div>
+<div id="workspace">
+    <aside id="docs-nav">
+        <div class="nav-title">Concepts</div>
+        <nav>
+            ${nav}
+        </nav>
+    </aside>
+    <main id="docs-content">
+        <article>
+${html}
+    </article>
+    </main>
+</div>
+</body>
+</html>
+`;
+}
+const DOCS_STYLESHEET = `/* Concept documentation — shares the explorer's palette. */
+:root {
+    --bg-editor: #1e1e1e;
+    --bg-sidebar: #252526;
+    --bg-inactive: #2d2d2d;
+    --bg-hover: #2a2d2e;
+    --text-primary: #d4d4d4;
+    --text-secondary: #abb2bf;
+    --text-muted: #858585;
+    --border: #3e3e3e;
+    --accent: #4ea1ff;
+    --code: #9cdcfe;
+}
+* { box-sizing: border-box; margin: 0; padding: 0; }
+body {
+    font-family: 'Segoe UI', system-ui, -apple-system, sans-serif;
+    background: var(--bg-editor);
+    color: var(--text-primary);
+    display: flex;
+    flex-direction: column;
+    min-height: 100vh;
+    line-height: 1.6;
+}
+#titlebar {
+    height: 34px;
+    background: #323233;
+    border-bottom: 1px solid #111;
+    display: flex;
+    align-items: center;
+    padding: 0 14px;
+    gap: 16px;
+    font-size: 13px;
+    flex-shrink: 0;
+    position: sticky;
+    top: 0;
+    z-index: 5;
+}
+#titlebar .app-name { color: var(--text-primary); font-weight: 600; }
+#surfaces { display: flex; gap: 14px; }
+#surfaces a { color: var(--text-muted); text-decoration: none; }
+#surfaces a:hover { color: var(--text-primary); }
+#surfaces a.current { color: var(--text-primary); border-bottom: 2px solid var(--accent); }
+#workspace { display: flex; flex: 1; align-items: flex-start; }
+#docs-nav {
+    width: 250px;
+    flex-shrink: 0;
+    background: var(--bg-sidebar);
+    border-right: 1px solid var(--border);
+    padding: 16px 0;
+    position: sticky;
+    top: 34px;
+    align-self: stretch;
+}
+.nav-title {
+    padding: 0 16px 8px;
+    font-size: 11px;
+    font-weight: 700;
+    text-transform: uppercase;
+    letter-spacing: 0.1em;
+    color: var(--text-muted);
+}
+#docs-nav nav { display: flex; flex-direction: column; }
+#docs-nav a {
+    padding: 6px 16px;
+    color: var(--text-secondary);
+    text-decoration: none;
+    font-size: 13px;
+    border-left: 2px solid transparent;
+}
+#docs-nav a:hover { background: var(--bg-hover); color: var(--text-primary); }
+#docs-nav a.current {
+    background: var(--bg-inactive);
+    color: var(--text-primary);
+    border-left-color: var(--accent);
+}
+#docs-content { flex: 1; min-width: 0; padding: 32px 40px 80px; }
+article { max-width: 68ch; }
+article h1 { font-size: 27px; font-weight: 600; margin-bottom: 18px; text-wrap: balance; }
+article h2 {
+    font-size: 19px;
+    font-weight: 600;
+    margin: 30px 0 10px;
+    padding-top: 10px;
+    border-top: 1px solid var(--border);
+    text-wrap: balance;
+}
+article h3 { font-size: 15px; font-weight: 600; margin: 20px 0 6px; }
+article p, article ul, article ol { margin-bottom: 13px; }
+article ul, article ol { padding-left: 22px; }
+article li { margin-bottom: 4px; }
+article a { color: var(--accent); text-decoration: none; }
+article a:hover { text-decoration: underline; }
+article code {
+    font-family: 'SF Mono', Menlo, Consolas, monospace;
+    font-size: 0.87em;
+    background: var(--bg-inactive);
+    color: var(--code);
+    padding: 1px 5px;
+    border-radius: 3px;
+}
+article pre {
+    background: var(--bg-sidebar);
+    border: 1px solid var(--border);
+    border-radius: 4px;
+    padding: 12px 14px;
+    overflow-x: auto;
+    margin-bottom: 14px;
+}
+article pre code { background: none; padding: 0; color: var(--text-primary); font-size: 12.5px; }
+article blockquote {
+    border-left: 3px solid var(--accent);
+    padding: 2px 0 2px 14px;
+    margin-bottom: 14px;
+    color: var(--text-secondary);
+}
+.table-wrap { overflow-x: auto; margin-bottom: 16px; }
+article table { border-collapse: collapse; font-size: 13px; min-width: 100%; }
+article th, article td {
+    border: 1px solid var(--border);
+    padding: 6px 10px;
+    text-align: left;
+    vertical-align: top;
+}
+article th { background: var(--bg-sidebar); font-weight: 600; }
+article td:not(:first-child) { font-variant-numeric: tabular-nums; }
+article hr { border: none; border-top: 1px solid var(--border); margin: 26px 0; }
+:focus-visible { outline: 2px solid var(--accent); outline-offset: 2px; }
+@media (max-width: 760px) {
+    #workspace { flex-direction: column; }
+    #docs-nav { width: 100%; position: static; border-right: none; border-bottom: 1px solid var(--border); }
+    #docs-content { padding: 20px; }
+}
+`;
+// ── Entry point ───────────────────────────────────────────────────────────────
+function buildDocsPages(outputDir) {
+    const { graph } = (0, buildEntityGraph_1.buildEntityGraph)();
+    const pages = fs_1.default
+        .readdirSync(DOCS_SOURCE_DIR)
+        .filter((entry) => entry.endsWith(".md"))
+        .map((entry) => {
+        var _a, _b;
+        const source = fs_1.default.readFileSync(path_1.default.join(DOCS_SOURCE_DIR, entry), "utf-8");
+        const { data, body } = parseFrontMatter(source);
+        if (!data.title)
+            throw new Error(`docs/${entry} is missing a "title" in front matter`);
+        return {
+            slug: entry.replace(/^\d+-/, "").replace(/\.md$/, ""),
+            title: data.title,
+            order: Number((_a = data.order) !== null && _a !== void 0 ? _a : 999),
+            summary: (_b = data.summary) !== null && _b !== void 0 ? _b : "",
+            body,
+        };
+    })
+        .sort((a, b) => a.order - b.order);
+    // Render everything before writing anything: an unknown fragment or a broken page
+    // should fail the build outright, not leave a half-written site behind.
+    const rendered = pages.map((page) => {
+        const expanded = expandFragments(page.body, graph);
+        const html = marked_1.marked.parse(expanded, { async: false })
+            // Wide tables scroll inside their own container rather than the page body.
+            .replace(/<table>/g, '<div class="table-wrap"><table>')
+            .replace(/<\/table>/g, "</table></div>");
+        return { page, html: renderPage(page, pages, html) };
+    });
+    const targetDir = path_1.default.join(outputDir, "docs");
+    fs_1.default.mkdirSync(targetDir, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(targetDir, "docs.css"), DOCS_STYLESHEET, "utf8");
+    rendered.forEach(({ page, html }) => {
+        fs_1.default.writeFileSync(path_1.default.join(targetDir, `${page.slug}.html`), html, "utf8");
+    });
+    return pages;
+}

package/dist/js/scripts/buildEntityGraph.d.ts

@@ -0,0 +1,129 @@
+import type { JSONSchema } from "../esse/utils";
+export type EntityGraphEdgeKind = "extends" | "contains" | "variant";
+export type EntityGraphLayer = "primitive" | "abstract" | "reusable" | "reference" | "definition" | "in-memory-entity" | "system" | "entity" | "entity-component" | "category" | "directory" | "application-parsing";
+export interface EntityGraphNodeManifest {
+    name: string;
+    isResult?: boolean;
+    isMonitor?: boolean;
+    defaultUnits?: string;
+}
+export interface EntityGraphNode {
+    /** Schema `$id`, dash-separated, e.g. "in-memory-entity/named-defaultable". */
+    id: string;
+    /** Source path relative to the repository root, e.g. "schema/material.json". */
+    path: string;
+    /**
+     * Path of the resolved copy on the published site. Derived from `$id` the same way
+     * JSONSchemasGenerator derives it, which is NOT always the source path: source
+     * directories may contain dashes (`properties_directory/non-scalar`) that become
+     * underscores once the id round-trips through `$id`.
+     */
+    publishedPath: string;
+    title: string;
+    description: string;
+    /** Top-level source directory, or "(root)" for schemas at the top of `schema/`. */
+    domain: string;
+    layer: EntityGraphLayer;
+    /** For "entity-component" nodes, the root entity the component belongs to. */
+    ownerEntity?: string;
+    inDegree: number;
+    outDegree: number;
+    propertyCount: number;
+    hasExample: boolean;
+    manifest?: EntityGraphNodeManifest;
+    /** Map coordinates, baked at build time so the client renders without laying out. */
+    x?: number;
+    y?: number;
+}
+export interface EntityGraphEdge {
+    source: string;
+    target: string;
+    kind: EntityGraphEdgeKind;
+    /** Property name for "contains" edges; "[]" suffix marks a reference through `items`. */
+    label?: string;
+    /** JSON pointer when the `$ref` carried a fragment, e.g. "/physicsBased". */
+    pointer?: string;
+}
+export interface EntityGraphMeta {
+    nodeCount: number;
+    edgeCount: number;
+    edgeCountsByKind: Record<EntityGraphEdgeKind, number>;
+    layerCounts: Record<string, number>;
+    sameDocumentRefCount: number;
+    schemasWithExample: number;
+    isolatedNodeCount: number;
+}
+export interface EntityGraph {
+    meta: EntityGraphMeta;
+    nodes: EntityGraphNode[];
+    edges: EntityGraphEdge[];
+}
+export interface EntityGraphLintResult {
+    failures: string[];
+    warnings: string[];
+}
+/**
+ * Isolated schemas at the time the lint baseline was taken; growth is reported, not failed.
+ * These are leaf definitions and externally-consumed formats that nothing else references.
+ */
+export declare const ISOLATED_NODE_BASELINE = 34;
+/**
+ * Maps a schema `$id` to the path of its resolved copy on the published site.
+ *
+ * Exactly invertible by {@link publishedPathToSchemaId}: an `$id` is a path with underscores
+ * replaced by dashes, so no `$id` ever contains an underscore and the mapping is injective.
+ *
+ * What is *not* recoverable is the **source** path, because a source directory may contain a
+ * literal dash (`properties_directory/non-scalar`) that the round-trip through `$id` turns into
+ * an underscore. Read `node.path` for that.
+ */
+export declare function schemaIdToPublishedPath(schemaId: string): string;
+/** Recovers a schema `$id` from the path of its published copy. */
+export declare function publishedPathToSchemaId(publishedPath: string): string;
+/** Builds the published-path to `$id` lookup, for callers that prefer a map to a function. */
+export declare function buildPublishedPathIndex(nodes: EntityGraphNode[]): Record<string, string>;
+/** Derives the `$id` a schema at this source path must declare, per `setSchemaIds`. */
+export declare function sourcePathToSchemaId(sourcePath: string): string;
+/**
+ * Assigns a layer to every schema. The classification is total by contract: an
+ * unclassifiable path is a lint failure, so a newly added top-level directory forces a
+ * deliberate decision here instead of silently landing in a catch-all bucket.
+ */
+export declare function classifyLayer(schemaId: string): {
+    layer: EntityGraphLayer;
+    ownerEntity?: string;
+} | undefined;
+/** Resolves a JSON pointer within a document, returning undefined when it does not exist. */
+export declare function resolveJsonPointer(document: unknown, pointer: string): unknown;
+interface RawReference {
+    ref: string;
+    /** Absent when no structural keyword encloses the `$ref` — an L4 failure. */
+    kind?: EntityGraphEdgeKind;
+    label?: string;
+}
+/**
+ * Collects every `$ref` in a schema together with the relationship it expresses.
+ *
+ * The relationship comes from the innermost enclosing structural keyword: a `$ref` inside
+ * `properties.foo.allOf[0]` extends, while one inside `allOf[0].properties.foo` is contained.
+ * The enclosing property name travels with the reference regardless of kind, so a union
+ * under `properties.data.oneOf` is recorded as a variant *of `data`*.
+ */
+export declare function collectReferences(schema: JSONSchema): RawReference[];
+export interface BuildEntityGraphResult {
+    graph: EntityGraph;
+    lint: EntityGraphLintResult;
+}
+export declare function buildEntityGraph(): BuildEntityGraphResult;
+/**
+ * L10 — validates the emitted graph against its schema.
+ *
+ * That schema lives here rather than in `schema/`: it describes a build artifact, not an
+ * entity of digital materials science, so it has no business in the corpus this tool
+ * measures. Imported rather than read from disk so it resolves identically whether the
+ * module runs from source or from the transpiled copy in `dist/`.
+ */
+export declare function validateEntityGraph(graph: EntityGraph): string[];
+/** Writes `graph.json` into the given directory, creating it when missing. */
+export declare function writeEntityGraph(graph: EntityGraph, outputDir: string): string;
+export {};