@dudousxd/nestjs-catalog 0.6.0 → 0.8.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.decorators.d.ts

@@ -31,6 +31,23 @@ export declare function CatalogType(options?: CatalogTypeOptions): ClassDecorato
  * Enriches one property. Everything it sets is tier 0 — the overlay can
  * override any of it at runtime without a migration, which is precisely why
  * these live in metadata rather than in the column definition.
+ *
+ * **This is also how a relation is enriched, and there is deliberately no
+ * `@CatalogRelation`.** The metadata is keyed by property name, and a
+ * `@ManyToOne` is a property; the registry looks the options up before it
+ * decides whether the field is a scalar or a link, so
+ * `@CatalogProperty({ displayName: 'Home base' })` on `Mvr.base` labels the link
+ * exactly as it labels a column. A second decorator would be a synonym for this
+ * one.
+ *
+ * A decorator that declared a relation *outright* — target, kind, join column —
+ * was considered and rejected twice over. Everything an ORM models is already
+ * derived, and a hand-written line that could restate it is a line that can
+ * disagree with the schema, which is the one thing this model does not allow.
+ * And the links an ORM genuinely cannot see are, in practice, the ones that
+ * cross applications: neither side's ORM holds both ends, so no decorator in
+ * either codebase can assert them. That is a curation act in the console, and it
+ * needs a route that does not exist yet.
  */
 export declare function CatalogProperty(options?: CatalogPropertyOptions): PropertyDecorator;
 export declare function readTypeOptions(target: unknown): CatalogTypeOptions;

package/dist/catalog.decorators.js

@@ -27,6 +27,23 @@ function CatalogType(options = {}) {
  * Enriches one property. Everything it sets is tier 0 — the overlay can
  * override any of it at runtime without a migration, which is precisely why
  * these live in metadata rather than in the column definition.
+ *
+ * **This is also how a relation is enriched, and there is deliberately no
+ * `@CatalogRelation`.** The metadata is keyed by property name, and a
+ * `@ManyToOne` is a property; the registry looks the options up before it
+ * decides whether the field is a scalar or a link, so
+ * `@CatalogProperty({ displayName: 'Home base' })` on `Mvr.base` labels the link
+ * exactly as it labels a column. A second decorator would be a synonym for this
+ * one.
+ *
+ * A decorator that declared a relation *outright* — target, kind, join column —
+ * was considered and rejected twice over. Everything an ORM models is already
+ * derived, and a hand-written line that could restate it is a line that can
+ * disagree with the schema, which is the one thing this model does not allow.
+ * And the links an ORM genuinely cannot see are, in practice, the ones that
+ * cross applications: neither side's ORM holds both ends, so no decorator in
+ * either codebase can assert them. That is a curation act in the console, and it
+ * needs a route that does not exist yet.
  */
 function CatalogProperty(options = {}) {
     return (target, propertyKey) => {

package/dist/catalog.environment.d.ts

@@ -291,6 +291,45 @@ export interface PromotableObjectType {
         unit?: string;
         classification?: string;
     }>;
+    /**
+     * The links the type declares, in the shape they are stored in.
+     *
+     * Absent from this interface until it was noticed that a promoted type arrived
+     * complete in every visible way — right properties, right table, right owner —
+     * and sat in the target's graph as an island. Nothing errored, nothing was
+     * reported, and the plan the operator approved said "nothing to promote" for a
+     * release whose only content was a link.
+     *
+     * Spelled out here rather than imported from the store package, which is the
+     * same reason `properties` is: the dependency runs the other way, and this
+     * side is the one both a MikroORM environment and anything else that ever
+     * holds a catalog have to satisfy. `kind` is a bare `string` for the reason the
+     * stored row gives — what comes back out of a JSON column is whatever some
+     * earlier version of some publisher put in, and it is narrowed where it is
+     * read, not asserted here.
+     *
+     * Optional, and read as `[]` wherever it is used. An environment whose rows
+     * predate the relations column holds `NULL` there, and requiring the field
+     * would force every hand-built promotable set to name something it has nothing
+     * to say about. "Absent" and "empty" are deliberately the same statement here,
+     * unlike on the publish wire: this shape is built by `readPromotable` in this
+     * process rather than arriving from a client of unknown vintage, and the plan
+     * an operator approves has to describe exactly what the apply will do. See
+     * `promoteType`.
+     */
+    relations?: Array<{
+        name: string;
+        displayName: string;
+        description?: string;
+        kind: string;
+        targetType: string;
+        localKey?: string;
+        nullable: boolean;
+        hidden: boolean;
+        position: number;
+        owner: boolean;
+        inverseName?: string;
+    }>;
 }
 export interface PromotableTransform {
     id: string;

package/dist/catalog.environment.js

@@ -732,5 +732,55 @@ function diffObjectType(existing, incoming) {
             to: gone,
         });
     }
+    diffs.push(...diffRelations(existing, incoming));
+    return diffs;
+}
+/**
+ * The links, compared the same way the properties above are — and named
+ * differently on purpose.
+ *
+ * **Why this exists at all.** Without it a promotion whose only difference is a
+ * link reports `unchanged`, so the plan says there is nothing to promote and the
+ * apply, driven by that plan, does nothing. The change is real, the operator is
+ * shown an empty diff, and the link stays behind in dev. A plan is what somebody
+ * approves; a change invisible in the plan is a change nobody approved.
+ *
+ * **`relations.removed`, not `relations.absentFromSource`.** The properties
+ * above borrow the softer word because nothing acts on them: `ensureType` is
+ * additive, so a column that vanished from the source keeps its data in the
+ * target. A link that vanished really is deleted there — `promoteType` assigns
+ * the source's links rather than merging them, because a link holds no data and
+ * keeping one the source deliberately dropped means the target asserts a join
+ * the schema no longer has. The field name has to say which of those two a
+ * reviewer is looking at.
+ *
+ * **`to` repeats the removed names rather than being empty.** The fingerprint an
+ * approval is compared against hashes each field's `to` value; an empty one
+ * would make "drops the link to Base" and "drops the link to Depot" hash
+ * identically, so a plan approved for one would be applicable as the other.
+ */
+function diffRelations(existing, incoming) {
+    const diffs = [];
+    // `?? []` on both sides, so an environment predating the relations column
+    // compares as holding none rather than as differing from everything.
+    const before = new Map((existing?.relations ?? []).map((relation) => [relation.name, relation]));
+    const after = new Map((incoming.relations ?? []).map((relation) => [relation.name, relation]));
+    const added = [...after.keys()].filter((name) => !before.has(name));
+    const changed = [...after.entries()]
+        .filter(([name, relation]) => {
+        const previous = before.get(name);
+        return previous !== undefined && stable(previous) !== stable(relation);
+    })
+        .map(([name]) => name);
+    const removed = [...before.keys()].filter((name) => !after.has(name));
+    if (added.length) {
+        diffs.push({ field: 'relations.added', from: [], to: added });
+    }
+    if (changed.length) {
+        diffs.push({ field: 'relations.changed', from: changed, to: changed });
+    }
+    if (removed.length) {
+        diffs.push({ field: 'relations.removed', from: removed, to: removed });
+    }
     return diffs;
 }

package/dist/catalog.pipeline.d.ts

@@ -84,6 +84,25 @@ export interface CatalogConnector {
      * view atomically. `incremental` reads only what changed since the last run
      * and carries the rest forward, which is cheaper but needs the source to
      * offer a watermark and the type to have a primary key to merge on.
+     *
+     * **`incremental` is blind to deletes, and that is structural rather than a
+     * gap in any particular fetcher.** A run asks its source for what changed
+     * since a watermark; a row physically removed from the source never changes
+     * again, so it is never returned again, so the carry-forward copies it into
+     * every subsequent snapshot indefinitely. Nothing goes wrong at any single
+     * step — the catalog simply never finds out, and every count and dashboard
+     * built on the type is quietly wrong from then on.
+     *
+     * Because that failure is silent, the pipeline **refuses an incremental load
+     * of a type for which no reconciliation strategy has been declared**: a full
+     * read on an interval, a source that soft-deletes where the watermark can see
+     * it, or an explicit "stale rows are acceptable here, because …". The
+     * declaration is per object type and lives in the host's
+     * `CATALOG_LOAD_EXPECTATIONS` (see `load-expectations.ts` in
+     * `@dudousxd/nestjs-catalog-pipeline`), because it is a statement about the
+     * data rather than about the connector reading it — the same type loaded by a
+     * workflow sink or by an application POSTing to the publish API has exactly
+     * the same problem.
      */
     mode?: 'full' | 'incremental';
     /**

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,7 +46,19 @@ 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>;

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,7 +31,6 @@ 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. */

package/dist/catalog.registry.js

@@ -27,6 +27,30 @@ const RELATION_KINDS = ['1:1', '1:m', 'm:1', 'm:n'];
 function isRelationKind(kind) {
     return RELATION_KINDS.includes(kind);
 }
+/**
+ * Which end of the link holds the key.
+ *
+ * Not simply `prop.owner`, and the difference matters. MikroORM sets that flag
+ * while resolving the *pair*, so it is dependable for `1:1` and `m:n` — where
+ * either side could plausibly own the key and only the mapping says which — and
+ * beside the point for the two kinds that have no choice: a `m:1` is the many
+ * end and therefore always holds the column, a `1:m` is the one end and
+ * therefore never does. Deriving those two from the kind rather than from a flag
+ * also means metadata assembled by hand (an `EntitySchema`, or a test) answers
+ * correctly without having to know the flag exists.
+ *
+ * `mappedBy` is checked first because it is unambiguous wherever it appears: the
+ * ORM only ever writes it on the inverse side.
+ */
+function isOwningSide(prop, kind) {
+    if (prop.mappedBy)
+        return false;
+    if (kind === '1:m')
+        return false;
+    if (kind === 'm:1')
+        return true;
+    return Boolean(prop.owner);
+}
 /** Classify one type name. Returns "unknown" when nothing matches. */
 function classify(raw) {
     const t = raw.toLowerCase();
@@ -154,41 +178,6 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             this.rebuild();
         return this.entityClasses.get(name);
     }
-    getGraph() {
-        const snapshot = this.getSnapshot();
-        const known = new Set(snapshot.types.map((t) => t.name));
-        const nodes = snapshot.types.map((t) => ({
-            id: t.name,
-            label: t.displayName,
-            group: t.group,
-            icon: t.icon,
-            propertyCount: t.properties.length,
-            relationCount: t.relations.length,
-        }));
-        // Both ends of a relation are declared, so every link shows up twice. Keep
-        // one edge per unordered pair per name so the graph does not double up.
-        const seen = new Set();
-        const edges = [];
-        for (const type of snapshot.types) {
-            for (const relation of type.relations) {
-                if (!known.has(relation.targetType))
-                    continue;
-                const pair = [type.name, relation.targetType].sort().join('::');
-                const key = `${pair}::${relation.name}`;
-                if (seen.has(key))
-                    continue;
-                seen.add(key);
-                edges.push({
-                    id: `${type.name}.${relation.name}`,
-                    source: type.name,
-                    target: relation.targetType,
-                    label: relation.displayName,
-                    kind: relation.kind,
-                });
-            }
-        }
-        return { nodes, edges };
-    }
     /** Tier-0 edit on a type. Never touches the database. */
     async patchType(typeName, patch) {
         const type = this.getType(typeName);
@@ -245,13 +234,21 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
         // here yields an empty array and a catalog that silently contains nothing.
         const all = this.orm.getMetadata().getAll();
         const types = [];
+        // Two passes, because a relation cannot be described without knowing the
+        // whole catalog: whether its target is published is a fact about the
+        // catalog, not about the entity being read, and a single pass would answer
+        // it differently depending on discovery order.
         this.entityClasses.clear();
+        const included = [];
         for (const meta of all.values()) {
             if (!this.shouldInclude(meta))
                 continue;
             this.entityClasses.set(meta.className, meta.class);
-            types.push(this.buildType(meta));
+            included.push(meta);
         }
+        const published = new Set(included.map((meta) => meta.className));
+        for (const meta of included)
+            types.push(this.buildType(meta, published));
         types.sort((a, b) => a.group.localeCompare(b.group) || a.displayName.localeCompare(b.displayName));
         this.version += 1;
         this.snapshot = {
@@ -279,7 +276,7 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             return false;
         return true;
     }
-    buildType(meta) {
+    buildType(meta, published) {
         const entityClass = meta.class;
         const declared = (0, catalog_decorators_1.readTypeOptions)(entityClass);
         const declaredProps = (0, catalog_decorators_1.readPropertyOptions)(entityClass);
@@ -298,16 +295,28 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             const fromOverlay = overlayProps[prop.name];
             const { displayName, description, hidden, order } = resolveFieldPresentation(prop.name, index, fromDecorator, fromOverlay);
             if (isRelationKind(prop.kind)) {
+                const targetType = prop.targetMeta?.className ?? String(prop.type);
                 relations.push({
                     name: prop.name,
                     displayName,
                     description,
                     kind: prop.kind,
-                    targetType: prop.targetMeta?.className ?? String(prop.type),
+                    targetType,
                     localKey: prop.fieldNames?.[0],
                     nullable: Boolean(prop.nullable),
                     hidden,
                     order,
+                    owner: isOwningSide(prop, prop.kind),
+                    // Either name identifies the same thing — the property at the other
+                    // end — and only one of them is ever set, on the side the ORM decided
+                    // is inverse. Read as one field because callers pairing the two ends
+                    // do not care which of the two spellings carried it.
+                    inverseName: prop.mappedBy || prop.inversedBy || undefined,
+                    targetPublished: published.has(targetType),
+                    // A relation is enriched on the same terms as a scalar: somebody said
+                    // something about it. Structure is not enrichment — every relation
+                    // here was derived, so its existence proves nothing about curation.
+                    enriched: Boolean(fromDecorator || fromOverlay),
                 });
                 return;
             }
@@ -341,7 +350,12 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             primaryKey: meta.primaryKeys ?? [],
             enriched: Object.keys(declared).length > 0 ||
                 Object.keys(overlay).length > 0 ||
-                properties.some((p) => p.enriched),
+                properties.some((p) => p.enriched) ||
+                // Relations count too. A type whose only human input is "this link is
+                // called Home base" has been worked on, and leaving it out of the tally
+                // put it back on the "nobody has named this" list the curator uses to
+                // decide what to do next.
+                relations.some((r) => r.enriched),
             properties,
             relations,
         };

package/dist/catalog.service.d.ts

@@ -1,9 +1,11 @@
 import { type CatalogModuleOptions } from './catalog.options';
+import type { CatalogPrincipal } from './catalog.principal';
 import { type CatalogQueryRelation, type CatalogQueryResult } from './catalog.query';
 import { CatalogRegistry } from './catalog.registry.base';
 import { type CatalogReadStore, type SnapshotRef } from './catalog.store';
 import type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogSnapshot } from './catalog.types';
 import { type AuditQuery, type CatalogAuditEvent, type CatalogWorkspaceStore, type Dashboard, type DashboardCard, type EmbeddedChart, type EmbeddedChartPlacement, type EmbeddedDashboard, type SaveQueryInput, type SavedQuery } from './catalog.workspace';
+import type { CatalogSearchResult } from './search.types';
 /**
  * Reads objects of any catalogued type through one endpoint.
  *
@@ -155,4 +157,19 @@ export declare class CatalogService {
     /** A whole dashboard, every chart resolved. */
     embedDashboard(dashboardId: string): Promise<EmbeddedDashboard>;
     listEvents(query: AuditQuery): Promise<CatalogAuditEvent[]>;
+    /**
+     * Everything matching `term` that this principal may see.
+     *
+     * @param principal the caller, when the host resolved one. **Optional, and its
+     * absence filters nothing** — the declare-and-enforce split written out above
+     * `mayWrite` in `catalog.principal.ts` means this library never resolves a
+     * principal itself. In a deployment with no guard, `GET /catalog` already
+     * hands over the whole snapshot, so search is exactly as open as what is
+     * already there and strictly narrower the moment a principal appears. See
+     * {@link visibleToPrincipal}.
+     */
+    search(term: string, options?: {
+        principal?: CatalogPrincipal;
+        limit?: number;
+    }): Promise<CatalogSearchResult>;
 }