@dudousxd/nestjs-catalog 0.7.0 → 0.9.0

package/dist/catalog.controller.d.ts

@@ -42,6 +42,12 @@ import { type Type } from '@nestjs/common';
  * every label one request at a time. Requiring admin would deny nothing and
  * would push a routine console action into the scope that manages principals.
  *
+ * **`GET search` is the one read here that looks at the principal.** Its scope
+ * is the unsurprising `catalog:read`; what is surprising is that it filters, in
+ * a library whose read routes deliberately do not. The reason it has to is on
+ * the route itself, and it is short: a host can wrap a read whose subject it
+ * knows, and cannot wrap one whose result set is chosen by a stranger's typing.
+ *
  * One consequence is worth stating rather than leaving to be discovered:
  * `shared` rides on the dashboard write routes, so `catalog:curate` carries the
  * power to hand a board to an outside application. That is not an oversight —

package/dist/catalog.controller.js

@@ -62,6 +62,12 @@ const catalog_workspace_1 = require("./catalog.workspace");
  * every label one request at a time. Requiring admin would deny nothing and
  * would push a routine console action into the scope that manages principals.
  *
+ * **`GET search` is the one read here that looks at the principal.** Its scope
+ * is the unsurprising `catalog:read`; what is surprising is that it filters, in
+ * a library whose read routes deliberately do not. The reason it has to is on
+ * the route itself, and it is short: a host can wrap a read whose subject it
+ * knows, and cannot wrap one whose result set is chosen by a stranger's typing.
+ *
  * One consequence is worth stating rather than leaving to be discovered:
  * `shared` rides on the dashboard write routes, so `catalog:curate` carries the
  * power to hand a board to an outside application. That is not an oversight —
@@ -95,6 +101,44 @@ function createCatalogController(path, guards, decorators = []) {
         graph() {
             return this.registry.getGraph();
         }
+        /**
+         * One term, across object types, properties, saved queries and dashboards.
+         *
+         * `catalog:read`, which is the scope of the four routes this is a shortcut
+         * to — `GET /catalog`, `GET saved-queries`, `GET dashboards` — and
+         * deliberately not narrower. A discovery route gated harder than the things
+         * it discovers is a route nobody can use; one gated softer is a way around
+         * them. Nothing here reaches a row of data or a statement: it returns names,
+         * labels and ids, which is a strict subset of what `GET /catalog` already
+         * hands the same caller.
+         *
+         * **The principal is passed, and this is one of two routes on this
+         * controller that filter by it.** The library's usual position is that reads
+         * apply no grants and a host wraps them — stated at length above `mayWrite`
+         * in `catalog.principal.ts`, and true of `GET objects/:name` right below.
+         * That position does not survive contact with a search box. A host can wrap
+         * `readObjects` because it knows the type being read and can decide; it
+         * cannot wrap this, because the whole result set is chosen by what somebody
+         * typed and the thing that must not come back is a NAME, which no wrapper
+         * downstream can distinguish from a name that was fine. Filtering has to
+         * happen where the candidates are enumerated, so it happens in
+         * `CatalogService.search`, and `visibleToPrincipal` is where to read the
+         * rules.
+         *
+         * The `@Req()` here is the same shape `actorOf` reads below, and for the
+         * same reason: a guard the host wrote put it there, and when no guard did,
+         * `undefined` arrives and nothing is filtered — see the service.
+         *
+         * Declared before every route carrying a parameter in the first segment,
+         * which today is none of them, so this is defensive rather than load-bearing.
+         * `events/traces` further down is the case where it is not.
+         */
+        search(q, limit, request) {
+            return this.service.search(q ?? '', {
+                principal: request?.principal,
+                limit: limit ? Number(limit) : undefined,
+            });
+        }
         type(name) {
             const type = this.registry.getType(name);
             if (!type)
@@ -347,6 +391,16 @@ function createCatalogController(path, guards, decorators = []) {
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "graph", null);
+    __decorate([
+        (0, common_1.Get)('search'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
+        __param(0, (0, common_1.Query)('q')),
+        __param(1, (0, common_1.Query)('limit')),
+        __param(2, (0, common_1.Req)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, String, Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "search", null);
     __decorate([
         (0, common_1.Get)('types/:name'),
         (0, catalog_route_auth_1.RequireScopes)('catalog:read'),

package/dist/catalog.events.d.ts

@@ -14,7 +14,7 @@
  */
 export declare const CATALOG_LIB = "catalog";
 /** Every event name this package emits. Exported so a watcher can claim them. */
-export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed", "query.shared", "dashboard.shared"];
+export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "overlay.reset", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed", "query.shared", "dashboard.shared"];
 export type CatalogEvent = (typeof CATALOG_EVENTS)[number];
 /**
  * Where each event sits in the life of one load.
@@ -81,6 +81,77 @@ export interface CatalogEventPayloads {
         property?: string;
         changed: string[];
     };
+    /**
+     * The whole overlay was discarded — every curated label, description, unit,
+     * order, hidden flag and classification in the catalog, in one request.
+     *
+     * An event of its own rather than a `type.curated` with the name left off.
+     * That payload leads with `typeName`, and a recorder lifts it into an indexed
+     * column; a reset has no single type, so it would land as a curation edit
+     * belonging to no type, indistinguishable from a malformed one. It is also a
+     * different act: `type.curated` records a decision about one column, this
+     * records the destruction of every such decision. Without it the trail could
+     * say who renamed one column and not who reverted every name at once — and
+     * both are `catalog:curate`, so the same curator can do either.
+     *
+     * **The classifications are why this is not merely tidy.** A classification is
+     * what `visibleToPrincipal` filters search results on, so a reset silently
+     * re-admits every classified property's *name* to searches by principals who
+     * could not see it an instant earlier. That is a change in who can see what,
+     * made by a route the controller documents as presentation-only.
+     *
+     * WHAT IT CARRIES, AND WHAT IT DELIBERATELY DOES NOT
+     * --------------------------------------------------
+     * The overlay is discarded rather than versioned, so nothing can be looked up
+     * afterwards: what is not in this payload is nowhere. That argues for carrying
+     * all of it, and all of it is the wrong answer — an audit row holding a
+     * verbatim copy of the overlay is a backup, and a backup nobody designed: no
+     * restore path, no retention policy of its own, and a JSON column that grows
+     * with the catalog. It would be read as one, too. The first person who needed
+     * it would find it, and the second would rely on it.
+     *
+     * So: a summary, drawn where the reader's question stops being "what did I
+     * lose" and starts being "give it back".
+     *
+     * - {@link typeNames}, because "somebody reset the catalog" is nearly useless
+     *   six months later and "was the work on `Dispute` in it" is what is actually
+     *   asked. Bounded by how many types anyone had curated.
+     * - {@link properties}, the scale of it as one number. The property *names* are
+     *   where a summary would turn into the dump.
+     * - {@link classifications} in full, values included, despite that line. They
+     *   are the one part of the overlay whose loss changes what the catalog shows
+     *   to whom, they are a small subset of it, and re-typing them is the only
+     *   recovery anybody can perform.
+     *
+     * **No `principalId`, and the absence is a limit rather than a decision that
+     * the actor does not matter.** `resetOverlay()` takes no principal, the route
+     * that calls it resolves none, and `RoutingCatalogRegistry` forwards the call
+     * by hand — so a field here would be `undefined` on every row, and an audit
+     * table lifts `principalId` into a column where empty reads as "nobody did
+     * this" rather than "this was not captured". `type.curated` has the same gap.
+     * Closing it means threading a principal through the controller, the service
+     * and every registry, which is a change to those, not a field on this payload.
+     *
+     * Emitted even when the overlay was empty, with zeroes. A trail that recorded
+     * only destructive resets cannot tell "nobody pressed it" from "somebody
+     * pressed it and nothing was there", and the second is worth seeing.
+     */
+    'overlay.reset': {
+        /** Every type that carried curation, so the trail names what was lost. */
+        typeNames: string[];
+        /** How many per-property entries went with them, across every type. */
+        properties: number;
+        /**
+         * Every classification that stopped applying, with its value — because that
+         * is what somebody restoring one needs, and after the reset there is nowhere
+         * left to read it.
+         */
+        classifications: Array<{
+            typeName: string;
+            property: string;
+            classification: string;
+        }>;
+    };
     /** A connector began pulling. */
     'connector.run.started': {
         connectorId: string;

package/dist/catalog.events.js

@@ -27,6 +27,7 @@ exports.CATALOG_EVENTS = [
     'snapshot.committed',
     'snapshot.dropped',
     'type.curated',
+    'overlay.reset',
     'connector.run.started',
     'connector.run.finished',
     'transform.changed',
@@ -67,6 +68,11 @@ exports.CATALOG_EVENT_PHASE = {
     // be complete is exactly the mechanism that will fail the build the day a new
     // event is added and nobody thinks about where it belongs.
     'type.curated': 2,
+    // The other curation event, ranked with the one it undoes. It carries no
+    // snapshot id either — a reset is not part of any load — so like the rank
+    // above this is never consulted, and it is written out because the `Record`
+    // has to be complete.
+    'overlay.reset': 2,
     // Sharing carries no snapshot id either, for the same reason curation does
     // not: it is a standalone act on a saved query or a board, not a step of any
     // load. So these ranks are never consulted, and they are written out for the

package/dist/catalog.overlay-store.d.ts

@@ -17,7 +17,28 @@ export declare class FileCatalogOverlayStore implements CatalogOverlayStore {
     load(): Promise<CatalogOverlay>;
     save(overlay: CatalogOverlay): Promise<void>;
 }
-/** For tests, and for deployments that want the catalog strictly read-only. */
+/**
+ * For tests, and for a single-process deployment content to lose every curated
+ * value when it restarts.
+ *
+ * **Not a read-only mode**, which is what this used to offer itself as. Nothing
+ * here refuses anything: `save` takes the overlay and keeps it, `PATCH
+ * /catalog/types/:name` answers 200 and emits `type.curated`, and the rename is
+ * real right up until the process ends. What it is not is *shared* — the overlay
+ * lives in one process's heap, so two replicas behind the same load balancer
+ * disagree about what a column is called, and which name a curator sees back
+ * depends on which pod took their request. A deployment that chose this store
+ * because the docblock promised read-only got precisely the writes it was trying
+ * to prevent, and got them inconsistently.
+ *
+ * There is no mode here to turn on instead, because read-only is not a store's
+ * decision. The writes arrive on routes that declare `catalog:curate`, and
+ * whether a deployment grants that scope is its guard's business — see the
+ * declare-and-enforce split in `catalog.route-auth.ts`. A store that threw would
+ * turn a policy answer ("you may not curate here") into a 500 from a route the
+ * library documents as working, and would put a second mechanism beside the one
+ * that already decides.
+ */
 export declare class InMemoryCatalogOverlayStore implements CatalogOverlayStore {
     private overlay;
     load(): Promise<CatalogOverlay>;

package/dist/catalog.overlay-store.js

@@ -13,12 +13,15 @@ class FileCatalogOverlayStore {
         try {
             const raw = await (0, promises_1.readFile)(this.path, 'utf8');
             const parsed = JSON.parse(raw);
-            if (parsed &&
-                typeof parsed === 'object' &&
-                'types' in parsed &&
-                typeof parsed.types === 'object') {
+            // Narrowed by a guard rather than asserted. The file on disk is edited by
+            // hand — that is the whole point of a JSON overlay — so its contents are
+            // exactly as trustworthy as whoever last opened it, and an assertion here
+            // would hand the registry a shape it promised to have rather than one it
+            // was checked for. The failure that buys is quiet: `types` arriving as
+            // `null` (an object, by `typeof`) or as an array reads as an overlay with
+            // no curation, and every label somebody wrote silently stops applying.
+            if (isOverlay(parsed))
                 return parsed;
-            }
             return { types: {} };
         }
         catch {
@@ -31,7 +34,28 @@ class FileCatalogOverlayStore {
     }
 }
 exports.FileCatalogOverlayStore = FileCatalogOverlayStore;
-/** For tests, and for deployments that want the catalog strictly read-only. */
+/**
+ * For tests, and for a single-process deployment content to lose every curated
+ * value when it restarts.
+ *
+ * **Not a read-only mode**, which is what this used to offer itself as. Nothing
+ * here refuses anything: `save` takes the overlay and keeps it, `PATCH
+ * /catalog/types/:name` answers 200 and emits `type.curated`, and the rename is
+ * real right up until the process ends. What it is not is *shared* — the overlay
+ * lives in one process's heap, so two replicas behind the same load balancer
+ * disagree about what a column is called, and which name a curator sees back
+ * depends on which pod took their request. A deployment that chose this store
+ * because the docblock promised read-only got precisely the writes it was trying
+ * to prevent, and got them inconsistently.
+ *
+ * There is no mode here to turn on instead, because read-only is not a store's
+ * decision. The writes arrive on routes that declare `catalog:curate`, and
+ * whether a deployment grants that scope is its guard's business — see the
+ * declare-and-enforce split in `catalog.route-auth.ts`. A store that threw would
+ * turn a policy answer ("you may not curate here") into a 500 from a route the
+ * library documents as working, and would put a second mechanism beside the one
+ * that already decides.
+ */
 class InMemoryCatalogOverlayStore {
     overlay = { types: {} };
     async load() {
@@ -42,3 +66,20 @@ class InMemoryCatalogOverlayStore {
     }
 }
 exports.InMemoryCatalogOverlayStore = InMemoryCatalogOverlayStore;
+/**
+ * Whether a parsed file is an overlay, checked to the depth that matters.
+ *
+ * The nesting below `types` is deliberately NOT walked. Every consumer reads it
+ * defensively — an entry that is missing, or missing the key it wanted, is the
+ * ordinary case for a type nobody has curated — so validating each entry would
+ * be re-implementing a tolerance the readers already have, and refusing the
+ * whole file over one malformed entry would discard every good one beside it.
+ */
+function isOverlay(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const types = Reflect.get(value, 'types');
+    // Not `typeof types === 'object'`, which admits `null` and arrays. Both parse
+    // from a hand-edited file, and both read downstream as "nothing is curated".
+    return Boolean(types) && typeof types === 'object' && !Array.isArray(types);
+}

package/dist/catalog.pipeline.d.ts

@@ -158,7 +158,28 @@ export interface CatalogTransform {
 }
 export interface TransformResult {
     rows: Array<Record<string, unknown>>;
-    /** Anything the code logged. Surfaced in the run, never in the rows. */
+    /**
+     * Anything the code logged. Surfaced in the run, never in the rows.
+     *
+     * "Anything the code logged" is meant literally, and in whichever language the
+     * transform is written: `console.log` and its siblings in JavaScript and
+     * TypeScript, `print` and anything written to `sys.stderr` in Python. A
+     * transform author's first instinct for finding out what their code is doing
+     * has to be the thing that works, because the alternative — an empty panel and
+     * no explanation — reads as "my code never ran" rather than as "you used the
+     * wrong function".
+     *
+     * In call order, with the channels interleaved rather than separated: a reader
+     * is reconstructing a sequence, and two lists cannot be zipped back together.
+     *
+     * **Bounded, by the runner, before it is returned.** These are lines user code
+     * chose and they cross a durable step boundary into the run record, so an
+     * unbounded capture would make the size of a `finishRun` write a property of
+     * somebody's source data. The bundled runner keeps the first 500 lines at
+     * 2,000 characters each and appends a line saying how many it dropped — a
+     * truncation nobody is told about is the same failure as a log nobody is told
+     * about. Consumers cap again for display, more tightly.
+     */
     logs: string[];
     elapsedMs: number;
 }

package/dist/catalog.registry.base.d.ts

@@ -1,4 +1,37 @@
 import type { CatalogGraph, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
+/**
+ * The ontology, as nodes and lines. **The one implementation of the edge rule.**
+ *
+ * Three rules, and all three exist because the naive version of each drew a
+ * picture that was wrong in a way nobody would notice:
+ *
+ * 1. **One edge per link.** A link declared at both ends produces two rows, and
+ *    keying the de-duplication on the property name only caught the case where
+ *    both ends happened to be spelled alike — so `Mvr.base` plus `Base.mvrs`,
+ *    the ordinary shape of a foreign key, drew two lines between the same pair
+ *    of nodes. See {@link linkKey} for how the two rows are recognised as one.
+ * 2. **Drawn from the end that holds the key**, so the arrow points the way a
+ *    join is written. Both ends are collected before either is chosen, because
+ *    otherwise the direction depends on which type was discovered first.
+ * 3. **No edge to a node that is not here.** An edge promises a node the reader
+ *    can open, and a target this catalog does not hold has none.
+ *
+ * Hidden relations are deliberately still drawn. Hiding is a statement about a
+ * table cell; a graph that quietly dropped edges would be a picture nobody could
+ * read as complete, which is the only thing a graph is for.
+ *
+ * WHY IT LIVES HERE, ON THE BASE CLASS'S OWN MODULE
+ * -------------------------------------------------
+ * Both registries had a copy — one derives the model from ORM metadata, the
+ * other reads it out of the database — in different packages, each carrying a
+ * comment asking the next person to change them together. A comment is not a
+ * mechanism, and a divergence here would be invisible: the two screens would
+ * simply disagree about how many links exist, and the copy that regressed would
+ * look exactly like the original bug (two edges per foreign key). The graph is a
+ * pure function of the snapshot, which is the one thing every registry already
+ * has to produce, so there was never anything for a subclass to decide.
+ */
+export declare function buildCatalogGraph(types: CatalogObjectTypeDef[]): CatalogGraph;
 /**
  * What the catalog knows about your types, however it came to know it.
  *
@@ -13,9 +46,41 @@ import type { CatalogGraph, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapsho
 export declare abstract class CatalogRegistry {
     abstract getSnapshot(): CatalogSnapshot;
     abstract getType(name: string): CatalogObjectTypeDef | undefined;
-    abstract getGraph(): CatalogGraph;
+    /**
+     * The ontology, drawn. Concrete, and the only implementation either registry
+     * runs.
+     *
+     * Not abstract because nothing about it varies: every edge and every node is
+     * read off the snapshot, and the snapshot is the abstract thing. The two
+     * registries did each override it with the same forty lines, which is how the
+     * edge rule came to exist twice in two packages — the failure this being a
+     * concrete method prevents. Where a registry *delegates* rather than derives
+     * (`RoutingCatalogRegistry` hands the whole call to whichever environment the
+     * request named) overriding is still right; deriving it a second time is not.
+     */
+    getGraph(): CatalogGraph;
     /** Presentation-only edits. Never a schema change. */
     abstract patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
     abstract patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
+    /**
+     * Discard every tier-0 edit at once.
+     *
+     * **An implementation that really discards must emit `overlay.reset`**, and
+     * the reason is an asymmetry this class would otherwise have: the two patches
+     * above are audited one field at a time, so a trail could say who renamed one
+     * column and not who reverted every name in the catalog — while both need only
+     * `catalog:curate`. The summary has to be built before the write; nothing
+     * versions an overlay, so afterwards there is nothing left to read.
+     *
+     * **Refusing is an implementation too, and refusing emits nothing.** A
+     * registry whose curated values have no derived layer underneath them has
+     * nothing to fall back to, so a reset there is destruction rather than a
+     * revert, and the throw is the whole answer — no act, no record of one.
+     * `StoredCatalogRegistry` is that case.
+     *
+     * Which of those a deployment runs is why the event is worth more than the
+     * call it accompanies: a registry that quietly resets without emitting looks
+     * exactly like one that never ran a reset at all.
+     */
     abstract resetOverlay(): Promise<void>;
 }

package/dist/catalog.registry.base.js

@@ -1,6 +1,93 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CatalogRegistry = void 0;
+exports.buildCatalogGraph = buildCatalogGraph;
+/**
+ * A key both ends of one link agree on, so the graph can draw it once.
+ *
+ * The owning end names the link — `Mvr.base` — and the inverse end, which knows
+ * the owner's property through `mappedBy`, arrives at the same string. That is
+ * the whole trick, and it is why `inverseName` is carried on the def at all.
+ *
+ * The fallback covers metadata that names neither end of the pair: both rows
+ * then reduce to the unordered pair plus the property name, which collapses the
+ * symmetric case (two `m:n` sides spelled alike) and leaves genuinely different
+ * names as two links. Guessing harder than that would mean pairing links by
+ * shape, and drawing one line where the schema has two is the worse error.
+ */
+function linkKey(holder, relation) {
+    if (relation.owner)
+        return `${holder}.${relation.name}`;
+    if (relation.inverseName)
+        return `${relation.targetType}.${relation.inverseName}`;
+    return `${[holder, relation.targetType].sort().join('::')}::${relation.name}`;
+}
+/**
+ * The ontology, as nodes and lines. **The one implementation of the edge rule.**
+ *
+ * Three rules, and all three exist because the naive version of each drew a
+ * picture that was wrong in a way nobody would notice:
+ *
+ * 1. **One edge per link.** A link declared at both ends produces two rows, and
+ *    keying the de-duplication on the property name only caught the case where
+ *    both ends happened to be spelled alike — so `Mvr.base` plus `Base.mvrs`,
+ *    the ordinary shape of a foreign key, drew two lines between the same pair
+ *    of nodes. See {@link linkKey} for how the two rows are recognised as one.
+ * 2. **Drawn from the end that holds the key**, so the arrow points the way a
+ *    join is written. Both ends are collected before either is chosen, because
+ *    otherwise the direction depends on which type was discovered first.
+ * 3. **No edge to a node that is not here.** An edge promises a node the reader
+ *    can open, and a target this catalog does not hold has none.
+ *
+ * Hidden relations are deliberately still drawn. Hiding is a statement about a
+ * table cell; a graph that quietly dropped edges would be a picture nobody could
+ * read as complete, which is the only thing a graph is for.
+ *
+ * WHY IT LIVES HERE, ON THE BASE CLASS'S OWN MODULE
+ * -------------------------------------------------
+ * Both registries had a copy — one derives the model from ORM metadata, the
+ * other reads it out of the database — in different packages, each carrying a
+ * comment asking the next person to change them together. A comment is not a
+ * mechanism, and a divergence here would be invisible: the two screens would
+ * simply disagree about how many links exist, and the copy that regressed would
+ * look exactly like the original bug (two edges per foreign key). The graph is a
+ * pure function of the snapshot, which is the one thing every registry already
+ * has to produce, so there was never anything for a subclass to decide.
+ */
+function buildCatalogGraph(types) {
+    const byLink = new Map();
+    for (const type of types) {
+        for (const relation of type.relations) {
+            if (!relation.targetPublished)
+                continue;
+            const key = linkKey(type.name, relation);
+            const seen = byLink.get(key);
+            // Replace only when this row is the owning one and the row already held
+            // is not: anything else keeps the first, so the edge order stays the type
+            // order rather than shuffling with every rebuild.
+            if (seen && (seen.relation.owner || !relation.owner))
+                continue;
+            byLink.set(key, { holder: type.name, relation });
+        }
+    }
+    return {
+        nodes: types.map((t) => ({
+            id: t.name,
+            label: t.displayName,
+            group: t.group,
+            icon: t.icon,
+            propertyCount: t.properties.length,
+            relationCount: t.relations.length,
+        })),
+        edges: [...byLink.values()].map(({ holder, relation }) => ({
+            id: `${holder}.${relation.name}`,
+            source: holder,
+            target: relation.targetType,
+            label: relation.displayName,
+            kind: relation.kind,
+        })),
+    };
+}
 /**
  * What the catalog knows about your types, however it came to know it.
  *
@@ -13,5 +100,20 @@ exports.CatalogRegistry = void 0;
  * data it was handed. Everything above this line works the same either way.
  */
 class CatalogRegistry {
+    /**
+     * The ontology, drawn. Concrete, and the only implementation either registry
+     * runs.
+     *
+     * Not abstract because nothing about it varies: every edge and every node is
+     * read off the snapshot, and the snapshot is the abstract thing. The two
+     * registries did each override it with the same forty lines, which is how the
+     * edge rule came to exist twice in two packages — the failure this being a
+     * concrete method prevents. Where a registry *delegates* rather than derives
+     * (`RoutingCatalogRegistry` hands the whole call to whichever environment the
+     * request named) overriding is still right; deriving it a second time is not.
+     */
+    getGraph() {
+        return buildCatalogGraph(this.getSnapshot().types);
+    }
 }
 exports.CatalogRegistry = CatalogRegistry;

package/dist/catalog.registry.d.ts

@@ -4,7 +4,7 @@ import { type OnModuleInit } from '@nestjs/common';
 import { type CatalogModuleOptions } from './catalog.options';
 import type { CatalogOverlayStore } from './catalog.overlay-store';
 import { CatalogRegistry } from './catalog.registry.base';
-import type { CatalogGraph, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
+import type { CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
 export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements OnModuleInit {
     private readonly orm;
     private readonly options;
@@ -31,11 +31,21 @@ export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements
      * generic object endpoint by guessing its name.
      */
     getEntityClass(name: string): EntityClass<Record<string, unknown>> | undefined;
-    getGraph(): CatalogGraph;
     /** Tier-0 edit on a type. Never touches the database. */
     patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
     /** Tier-0 edit on a property. Never touches the database. */
     patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
+    /**
+     * Drop every tier-0 edit, and leave a record that it happened.
+     *
+     * The summary is taken before the overlay is cleared because it is the only
+     * record there will ever be: nothing versions an overlay, so the discarded
+     * values are gone the instant the store is written. See `overlay.reset` in
+     * `catalog.events.ts` for why the payload is a summary and not a copy.
+     *
+     * Emitted after the write, like the two patches above, so the trail says what
+     * happened rather than what was about to.
+     */
     resetOverlay(): Promise<void>;
     private persist;
     private rebuild;