@mat3ra/esse 2026.8.27-0 → 2026.9.5-0

package/README.md

@@ -12,7 +12,7 @@ The latest variants of schemas and examples are available at [schemas.mat3ra.com
 
 - **[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.
+- **[Ontology](https://schemas.mat3ra.com/map/)** — an interactive map of the ontology: every entity type and every relationship the schemas declare between them (`extends`, `contains`, `variant`), 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.
 
@@ -160,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, 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.
+5. GH workflow is used to generate the fully resolved file (without "$ref"s and "$allOf" etc.) and examples, render the documentation and the ontology 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.

package/dist/js/scripts/buildDocsPages.js

@@ -157,6 +157,28 @@ function categorizationSchemesFragment(graph) {
 
 Entities carrying a tiered \`categories\` field: ${carrierList || "_none_"}.`;
 }
+/**
+ * The three relation kinds, with their ontological reading alongside the JSON Schema
+ * keyword that expresses each. Counts come from the graph, so the prose calling these
+ * "the familiar ontological relations" cannot drift from what the corpus declares.
+ */
+function ontologyRelationsFragment(graph) {
+    const kinds = [
+        ["`extends`", "`allOf`", "**is a** (subsumption)", "extends"],
+        ["`contains`", "`properties` / `items`", "**has a** (composition)", "contains"],
+        ["`variant`", "`oneOf` / `anyOf`", "**is one of** (disjunction)", "variant"],
+    ];
+    const counts = graph.meta.edgeCountsByKind;
+    const rows = kinds.map(([relation, keyword, reading, key]) => [
+        relation,
+        keyword,
+        reading,
+        String(counts[key]),
+    ]);
+    return `${table(["Relation", "Declared by", "Reads as", "Edges"], rows)}
+
+Across ${graph.meta.nodeCount} entity types, ${graph.meta.edgeCount} declared relationships.`;
+}
 function layerInventoryFragment(graph) {
     const rows = Object.entries(graph.meta.layerCounts)
         .sort((a, b) => b[1] - a[1])
@@ -186,6 +208,8 @@ function expandFragments(body, graph) {
                 ]);
             case "layer-inventory":
                 return layerInventoryFragment(graph);
+            case "ontology-relations":
+                return ontologyRelationsFragment(graph);
             case "categorization-schemes":
                 return categorizationSchemesFragment(graph);
             case "hub-table":
@@ -215,18 +239,19 @@ function renderPage(page, pages, html) {
 <head>
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>${escapeHtml(page.title)} — ESSE</title>
+    <title>${escapeHtml(page.title)} — AI4Materials</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>
+    <span class="app-name">AI4Materials<span class="app-name-suffix">: data standards</span></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>
+        <a href="../map/index.html">Ontology</a>
     </nav>
+    <span id="titlebar-tagline">ESSE &middot; materials science ontology</span>
 </div>
 <div id="workspace">
     <aside id="docs-nav">
@@ -283,10 +308,15 @@ body {
     z-index: 5;
 }
 #titlebar .app-name { color: var(--text-primary); font-weight: 600; }
+/* Completes the wordmark so the name never reads as a dangling fragment. */
+#titlebar .app-name-suffix { color: var(--text-muted); font-weight: 400; }
+@media (max-width: 700px) { #titlebar .app-name-suffix { display: none; } }
 #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); }
+#titlebar-tagline { margin-left: auto; color: var(--text-muted); }
+@media (max-width: 640px) { #titlebar-tagline { display: none; } }
 #workspace { display: flex; flex: 1; align-items: flex-start; }
 #docs-nav {
     width: 250px;

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

@@ -7,6 +7,17 @@ export interface EntityGraphNodeManifest {
     isMonitor?: boolean;
     defaultUnits?: string;
 }
+/**
+ * Navigation facets derived at build time. Keys are sorted; a value is the slug as the
+ * corpus spells it — the enum a CateCom vocabulary schema narrows, or a path segment for
+ * M-CODE and the catalogues. A narrowing to several values is joined with "|" in enum
+ * order, because such a schema is the branch rather than a point on the ladder.
+ *
+ * Present on every `category` and `directory` node, absent on every other layer.
+ */
+export type EntityGraphFacets = Record<string, string>;
+/** The five coordinate fields of `core/reusable/categories`, in ladder order. */
+export declare const CATECOM_FIELDS: readonly ["tier1", "tier2", "tier3", "type", "subtype"];
 export interface EntityGraphNode {
     /** Schema `$id`, dash-separated, e.g. "in-memory-entity/named-defaultable". */
     id: string;
@@ -31,6 +42,8 @@ export interface EntityGraphNode {
     propertyCount: number;
     hasExample: boolean;
     manifest?: EntityGraphNodeManifest;
+    /** Navigation facets — see EntityGraphFacets. Category and directory nodes only. */
+    facets?: EntityGraphFacets;
     /** Map coordinates, baked at build time so the client renders without laying out. */
     x?: number;
     y?: number;
@@ -110,6 +123,29 @@ interface RawReference {
  * under `properties.data.oneOf` is recorded as a variant *of `data`*.
  */
 export declare function collectReferences(schema: JSONSchema): RawReference[];
+interface LoadedSchema {
+    sourcePath: string;
+    relativePath: string;
+    schema: JSONSchema;
+}
+interface FacetContext {
+    nodes: Map<string, EntityGraphNode>;
+    schemaById: Map<string, LoadedSchema>;
+    schemasBySourcePath: Map<string, LoadedSchema>;
+    /** `extends` targets per source id, sorted, so the upward walk is deterministic. */
+    extendsTargets: Map<string, string[]>;
+    /** Target of the `categories` property edge, per directory node id. */
+    categoriesTarget: Map<string, string>;
+    coordinateMemo: Map<string, EntityGraphFacets>;
+}
+/**
+ * Facets for one node, or undefined when no rule covers it.
+ *
+ * Category nodes carry their scheme's coordinate (CateCom's ladder or M-CODE's axes);
+ * directory nodes carry the catalogue they belong to, that catalogue's own axis, and — when
+ * the entry declares a `categories` property — the coordinate it is filed at.
+ */
+export declare function deriveFacets(node: EntityGraphNode, context: FacetContext): EntityGraphFacets | undefined;
 export interface BuildEntityGraphResult {
     graph: EntityGraph;
     lint: EntityGraphLintResult;

package/dist/js/scripts/buildEntityGraph.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ISOLATED_NODE_BASELINE = void 0;
+exports.ISOLATED_NODE_BASELINE = exports.CATECOM_FIELDS = void 0;
 exports.schemaIdToPublishedPath = schemaIdToPublishedPath;
 exports.publishedPathToSchemaId = publishedPathToSchemaId;
 exports.buildPublishedPathIndex = buildPublishedPathIndex;
@@ -11,6 +11,7 @@ exports.sourcePathToSchemaId = sourcePathToSchemaId;
 exports.classifyLayer = classifyLayer;
 exports.resolveJsonPointer = resolveJsonPointer;
 exports.collectReferences = collectReferences;
+exports.deriveFacets = deriveFacets;
 exports.buildEntityGraph = buildEntityGraph;
 exports.validateEntityGraph = validateEntityGraph;
 exports.writeEntityGraph = writeEntityGraph;
@@ -34,6 +35,8 @@ const ajv_1 = require("../utils/ajv");
 const filesystem_1 = require("../utils/filesystem");
 const entity_graph_schema_json_1 = __importDefault(require("./entity_graph.schema.json"));
 const entityGraphLayout_1 = require("./entityGraphLayout");
+/** The five coordinate fields of `core/reusable/categories`, in ladder order. */
+exports.CATECOM_FIELDS = ["tier1", "tier2", "tier3", "type", "subtype"];
 /**
  * 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.
@@ -210,6 +213,164 @@ function readPropertiesManifest() {
         return {};
     return ((_a = js_yaml_1.default.load(fs_1.default.readFileSync(settings_1.PROPERTIES_MANIFEST_PATH, "utf-8"))) !== null && _a !== void 0 ? _a : {});
 }
+// ── Facets ────────────────────────────────────────────────────────────────────
+const ENUM_HOLDER = /^(enum_options|enum|enums)$/;
+const DIMENSIONALITY = /^(zero|one|two|three)-dimensional$/;
+const OPERATIONS_PREFIX = "materials-category-components/operations/";
+const VALUE_SHAPES = ["scalar", "non-scalar", "structural", "elemental", "workflow"];
+const METHOD_BRANCHES = ["mathematical", "physical"];
+/** Source path segments below `schema/`, so `non-scalar` keeps the dash its `$id` loses. */
+function sourceSegments(node) {
+    return node.path
+        .replace(/^schema\//, "")
+        .replace(/\.json$/, "")
+        .split("/");
+}
+function sortedFacets(facets) {
+    return Object.fromEntries(Object.entries(facets).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * Which of the five CateCom fields this vocabulary schema narrows, each resolved to its enum.
+ *
+ * The enum is the coordinate, not the path segment: `fapprx/basisexp.json` narrows `tier2`
+ * to `basisExp`, and for methods the first segment (`mathematical`, `physical`) is not a tier
+ * at all — so counting path depth gets the ladder wrong.
+ */
+function ownNarrowings(id, context) {
+    var _a;
+    const loaded = context.schemaById.get(id);
+    if (!loaded)
+        return {};
+    const properties = ((_a = loaded.schema.properties) !== null && _a !== void 0 ? _a : {});
+    const narrowed = {};
+    exports.CATECOM_FIELDS.forEach((field) => {
+        var _a;
+        const property = properties[field];
+        if (!property)
+            return;
+        let values = Array.isArray(property.enum) ? property.enum : undefined;
+        if (!values && typeof property.$ref === "string") {
+            const [filePart, pointerPart] = property.$ref.split("#");
+            const target = (_a = context.schemasBySourcePath.get(path_1.default.resolve(path_1.default.dirname(loaded.sourcePath), filePart))) === null || _a === void 0 ? void 0 : _a.schema;
+            const fragment = resolveJsonPointer(target, `/${(pointerPart !== null && pointerPart !== void 0 ? pointerPart : "").replace(/^\//, "")}`);
+            values = fragment === null || fragment === void 0 ? void 0 : fragment.enum;
+        }
+        if (Array.isArray(values) && values.length > 0) {
+            narrowed[field] = values.map(String).join("|");
+        }
+    });
+    return narrowed;
+}
+/** Ancestors' narrowings (walking `extends` within the category layer), then this node's; own wins. */
+function catecomCoordinate(id, context) {
+    var _a;
+    const memoised = context.coordinateMemo.get(id);
+    if (memoised)
+        return memoised;
+    context.coordinateMemo.set(id, {});
+    const coordinate = {};
+    ((_a = context.extendsTargets.get(id)) !== null && _a !== void 0 ? _a : [])
+        .filter((parent) => { var _a; return ((_a = context.nodes.get(parent)) === null || _a === void 0 ? void 0 : _a.layer) === "category"; })
+        .forEach((parent) => Object.assign(coordinate, catecomCoordinate(parent, context)));
+    Object.assign(coordinate, ownNarrowings(id, context));
+    context.coordinateMemo.set(id, coordinate);
+    return coordinate;
+}
+/** Last segment of the first operation reached walking `extends` upward. */
+function mcodeOperation(id, context, seen = new Set()) {
+    var _a;
+    if (seen.has(id))
+        return undefined;
+    seen.add(id);
+    const parents = (_a = context.extendsTargets.get(id)) !== null && _a !== void 0 ? _a : [];
+    const direct = parents.find((parent) => parent.startsWith(OPERATIONS_PREFIX));
+    if (direct)
+        return direct.split("/").pop();
+    return parents.map((parent) => mcodeOperation(parent, context, seen)).find(Boolean);
+}
+/**
+ * Facets for one node, or undefined when no rule covers it.
+ *
+ * Category nodes carry their scheme's coordinate (CateCom's ladder or M-CODE's axes);
+ * directory nodes carry the catalogue they belong to, that catalogue's own axis, and — when
+ * the entry declares a `categories` property — the coordinate it is filed at.
+ */
+function deriveFacets(node, context) {
+    if (node.layer !== "category" && node.layer !== "directory")
+        return undefined;
+    const segments = sourceSegments(node);
+    const [, second, third, fourth] = segments;
+    const holder = ENUM_HOLDER.test(segments[segments.length - 1]);
+    const facets = {};
+    if (node.layer === "category") {
+        if (node.domain === "models_category" || node.domain === "methods_category") {
+            facets.scheme = "catecom";
+            if (node.domain === "methods_category")
+                facets.branch = second;
+            if (holder) {
+                facets.role = "enum-options";
+            }
+            else {
+                facets.role = "vocabulary";
+                Object.assign(facets, catecomCoordinate(node.id, context));
+            }
+        }
+        else if (node.domain === "materials_category") {
+            facets.scheme = "mcode";
+            facets.role = "recipe";
+            facets.structuralClass = second.replace(/_structures$/, "").replace(/_/g, "-");
+            facets.dimensionality = third;
+            const operation = mcodeOperation(node.id, context);
+            if (operation)
+                facets.operation = operation;
+        }
+        else if (node.domain === "materials_category_components" && second === "entities") {
+            facets.scheme = "mcode";
+            facets.role = "entity";
+            facets.entityRole = third;
+            // Dimensionality sits one segment deeper here than under materials_category.
+            facets.dimensionality = fourth;
+        }
+        else if (node.domain === "materials_category_components" && second === "operations") {
+            facets.scheme = "mcode";
+            facets.role = holder ? "enum-options" : "operation";
+            facets.operationKind = fourth;
+        }
+        else {
+            return undefined;
+        }
+        return sortedFacets(facets);
+    }
+    facets.catalogue = node.domain.replace(/_directory$/, "").replace(/_/g, "-");
+    if (holder) {
+        facets.role = "enum-options";
+        return sortedFacets(facets);
+    }
+    if (second === "legacy")
+        facets.legacy = "true";
+    if (node.domain === "properties_directory" && VALUE_SHAPES.includes(second)) {
+        facets.valueShape = second;
+    }
+    if (node.domain === "software_directory")
+        facets.softwareKind = second;
+    if (node.domain === "methods_directory" && METHOD_BRANCHES.includes(second)) {
+        facets.branch = second;
+    }
+    if (node.domain === "context_providers_directory") {
+        facets.scope = second === "by_application" ? "by-application" : "generic";
+        if (second === "by_application")
+            [facets.application] = third.split("_");
+    }
+    const coordinate = context.categoriesTarget.get(node.id);
+    if (coordinate) {
+        const inherited = catecomCoordinate(coordinate, context);
+        exports.CATECOM_FIELDS.forEach((field) => {
+            if (inherited[field])
+                facets[field] = inherited[field];
+        });
+    }
+    return sortedFacets(facets);
+}
 function buildEntityGraph() {
     const failures = [];
     const warnings = [];
@@ -350,6 +511,50 @@ function buildEntityGraph() {
             ...(((_a = entry.defaults) === null || _a === void 0 ? void 0 : _a.units) ? { defaultUnits: String(entry.defaults.units) } : {}),
         };
     });
+    // L11 — facets are total on the category and directory layers, and well formed.
+    // Assigned after the edges exist (the CateCom walk and the `categories` join both need
+    // them) and before layout, so node key order stays deterministic.
+    const extendsTargets = new Map();
+    const categoriesTarget = new Map();
+    edges.forEach((edge) => {
+        var _a, _b;
+        if (edge.kind === "extends") {
+            if (!extendsTargets.has(edge.source))
+                extendsTargets.set(edge.source, []);
+            extendsTargets.get(edge.source).push(edge.target);
+        }
+        if (edge.kind === "contains" && edge.label === "categories") {
+            if (((_a = nodes.get(edge.source)) === null || _a === void 0 ? void 0 : _a.layer) === "directory" &&
+                ((_b = nodes.get(edge.target)) === null || _b === void 0 ? void 0 : _b.layer) === "category") {
+                categoriesTarget.set(edge.source, edge.target);
+            }
+        }
+    });
+    extendsTargets.forEach((targets) => targets.sort());
+    const facetContext = {
+        nodes,
+        schemaById: new Map(loadedSchemas
+            .map((item) => [nodeIdBySourcePath.get(item.sourcePath), item])
+            .filter(([id]) => Boolean(id))),
+        schemasBySourcePath,
+        extendsTargets,
+        categoriesTarget,
+        coordinateMemo: new Map(),
+    };
+    [...nodes.keys()].sort().forEach((id) => {
+        const node = nodes.get(id);
+        if (node.layer !== "category" && node.layer !== "directory")
+            return;
+        const facets = deriveFacets(node, facetContext);
+        if (!facets || Object.keys(facets).length === 0) {
+            failures.push(`L11 ${node.path}: no facet rule covers this ${node.layer} path — add one to deriveFacets`);
+            return;
+        }
+        if (facets.dimensionality && !DIMENSIONALITY.test(facets.dimensionality)) {
+            failures.push(`L11 ${node.path}: dimensionality "${facets.dimensionality}" is not <zero|one|two|three>-dimensional`);
+        }
+        node.facets = facets;
+    });
     const sortedNodes = (0, entityGraphLayout_1.computeEntityGraphLayout)([...nodes.values()].sort((a, b) => a.id.localeCompare(b.id)));
     const sortedEdges = edges.sort((a, b) => {
         var _a, _b, _c, _d;

package/dist/js/scripts/checkSiteLinks.js

@@ -8,7 +8,7 @@ exports.checkSiteLinks = checkSiteLinks;
  * Verifies that every internal link in the assembled site resolves.
  *
  * The site is stitched together from four sources — resolved schemas, the concept docs, the
- * explorer and the Entity Map — each of which links into the others. Nothing else checks that
+ * explorer and the ontology map — each of which links into the others. Nothing else checks that
  * those links land anywhere, and a stale href is invisible until someone clicks it.
  *
  * External URLs are not fetched; this is a build step, not a crawler.

package/dist/js/scripts/entity_graph.schema.json

@@ -154,6 +154,13 @@
                         "required": [
                             "name"
                         ]
+                    },
+                    "facets": {
+                        "description": "Navigation facets derived at build time: the CateCom coordinate a vocabulary schema narrows to, the M-CODE axes carried in a materials path, or the catalogue and axis a directory entry belongs to. Present on every category and directory node.",
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
                     }
                 },
                 "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mat3ra/esse",
-    "version": "2026.8.27-0",
+    "version": "2026.9.5-0",
     "description": "Mat3ra's Excellent Source of Schemas and Examples (ESSE) for Digital Materials R&D",
     "scripts": {
         "transpile": "tsc -p tsconfig-transpile.json",
@@ -8,6 +8,7 @@
         "build-entity-graph": "ts-node build_entity_graph.ts --output ./site",
         "lint-entity-graph": "ts-node build_entity_graph.ts",
         "build-docs-pages": "ts-node build_docs_pages.ts",
+        "build-site": "npm run transpile-and-build-assets && ts-node build_site.ts && npm run check-site-links -- --site site",
         "check-site-links": "ts-node check_site_links.ts",
         "compile-types": "ts-node compile_ts.ts",
         "transpile-and-build-assets": "npm run set-schema-ids && npm run build-schemas && npm run compile-types && npm run transpile",