@dudousxd/nestjs-catalog 0.5.0 → 0.7.0

package/dist/catalog.controller.js

@@ -16,6 +16,7 @@ exports.createCatalogController = createCatalogController;
 const common_1 = require("@nestjs/common");
 const catalog_query_cache_1 = require("./catalog.query-cache");
 const catalog_registry_base_1 = require("./catalog.registry.base");
+const catalog_route_auth_1 = require("./catalog.route-auth");
 const catalog_service_1 = require("./catalog.service");
 const catalog_workspace_1 = require("./catalog.workspace");
 /**
@@ -23,6 +24,52 @@ const catalog_workspace_1 = require("./catalog.workspace");
  * guards both come from `forRoot`. A library that hardcodes either one forces
  * every host app to accept its idea of auth, which for an endpoint that
  * enumerates every table in the database is not a reasonable default.
+ *
+ * ---------------------------------------------------------------------------
+ * Every route declares what it needs, and four of the choices are not obvious.
+ *
+ * Declaring is not enforcing — see `catalog.route-auth.ts` — but an *absent*
+ * declaration is a declaration too: it tells a host's guard that authenticated
+ * is enough. So a route left bare is not "undecided", it is "open", and for a
+ * long time this controller said that about arbitrary SQL and about every
+ * curation edit.
+ *
+ * **Arbitrary SQL is `catalog:admin`, not `catalog:read`.** `catalog:read` is
+ * "read object metadata and rows" — rows *of a catalogued type*, through a
+ * route that names one. `POST query` is not bounded by the model at all: it is
+ * whatever the store's read connection can select, and in the shipped MikroORM
+ * store that connection is the catalog's own schema. `SELECT * FROM
+ * catalog_principal` returns every principal's scopes, grants and `keyHash` —
+ * the SHA-256 of its static key — which is not something a reporting principal
+ * should be able to fetch, and is not reachable from any other route here. That
+ * is squarely the population `catalog:admin` ("manage principals and grants")
+ * describes.
+ *
+ * **So the two saved-query write routes are `catalog:admin` too.** They accept
+ * a `sql` field, and `POST saved-queries` + `POST saved-queries/:id/run` is
+ * `POST query` in two requests. Gating one and not the others would make the
+ * strict declaration decoration.
+ *
+ * **Running a saved query is only `catalog:read`.** The capability being held
+ * back is *choosing what SQL runs*, not *seeing a result*: a saved query is an
+ * artefact somebody with the authoring scope vetted, and running one is reading
+ * a report they wrote. Gating execution instead would be worse in both
+ * directions — it would stop an analyst opening a dashboard, and it would let an
+ * unprivileged caller plant a statement and wait for a privileged one to run it.
+ *
+ * **`POST reset` is `catalog:curate`, not `catalog:admin`.** It discards exactly
+ * what the two `PATCH`es write, catalog-wide, and a curator can already blank
+ * 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.
+ *
+ * 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 —
+ * it is one field on an authoring route, and splitting it would mean a route
+ * whose only job is to flip a boolean. What makes it accountable is that the
+ * act is audited, in both directions and including by deletion; see the
+ * sharing block in `catalog.service.ts`.
+ * ---------------------------------------------------------------------------
  */
 function createCatalogController(path, guards, decorators = []) {
     let CatalogController = class CatalogController {
@@ -88,11 +135,24 @@ function createCatalogController(path, guards, decorators = []) {
                 snapshot,
             });
         }
-        /** What an ad-hoc query may select from, and whether it can run at all. */
+        /**
+         * What an ad-hoc query may select from, and whether it can run at all.
+         *
+         * `catalog:read` and not the scope the query route itself needs: this
+         * describes the catalogued types' physical relations and their columns,
+         * which is the same model `GET types/:name` already hands a reader. It is a
+         * schema panel, not an execution surface.
+         */
         queryRelations() {
             return this.service.queryRelations();
         }
-        /** Run one read-only statement. */
+        /**
+         * Run one read-only statement.
+         *
+         * `catalog:admin`. Read-only is not the same as bounded: this reaches
+         * whatever the store's connection reaches, which includes the catalog's own
+         * governance tables. See the block above the controller.
+         */
         runQuery(body) {
             return this.service.runQuery(body ?? { sql: '' });
         }
@@ -106,19 +166,43 @@ function createCatalogController(path, guards, decorators = []) {
         savedQueries() {
             return this.service.listSavedQueries();
         }
-        saveSavedQuery(body) {
-            return this.service.saveQuery(body, body?.createdBy ?? 'console');
+        /** Takes a `sql` field, so it is the SQL scope and not a workspace one. */
+        saveSavedQuery(body, request) {
+            return this.service.saveQuery(body, actorOf(request, body?.createdBy));
         }
         savedQuery(id) {
             return this.service.getSavedQuery(id);
         }
-        patchSavedQuery(id, body) {
-            return this.service.updateSavedQuery(id, body);
+        /**
+         * The body names no actor, deliberately — unlike the create route above,
+         * which has always let one be declared because `createdBy` is a stored
+         * field. Here the only consumer of the name is the audit entry a `shared`
+         * toggle produces, and a caller that can put any string into the audit trail
+         * is worse than one the trail records as the console.
+         *
+         * `catalog:admin` because the body may carry `sql`. A patch that can rewrite
+         * the statement is the authoring capability whatever else it is used for.
+         */
+        patchSavedQuery(id, body, request) {
+            return this.service.updateSavedQuery(id, body, actorOf(request));
         }
-        removeSavedQuery(id) {
-            return this.service.deleteSavedQuery(id).then((deleted) => ({ deleted }));
+        /**
+         * `catalog:curate` and not the SQL scope: deleting takes a statement away
+         * rather than choosing one. It is the same workspace-authoring act as
+         * deleting a board.
+         *
+         * The principal is passed for the same reason the `PATCH` above takes one —
+         * deleting a shared query revokes outside access, and that is recorded.
+         */
+        removeSavedQuery(id, request) {
+            return this.service.deleteSavedQuery(id, actorOf(request)).then((deleted) => ({ deleted }));
         }
-        /** Run a saved query, honouring the cache TTL it was saved with. */
+        /**
+         * Run a saved query, honouring the cache TTL it was saved with.
+         *
+         * `catalog:read`, unlike writing one. What is held back upstream is
+         * choosing what SQL runs; this runs a statement somebody already vetted.
+         */
         runSavedQuery(id, body) {
             return this.service.runSavedQuery(id, body?.maxRows);
         }
@@ -138,23 +222,43 @@ function createCatalogController(path, guards, decorators = []) {
         dashboards() {
             return this.service.listDashboards();
         }
-        createDashboard(body) {
-            return this.service.saveDashboard(body, body?.createdBy ?? 'console');
+        /**
+         * `shared` is declared rather than merely passed through.
+         *
+         * It is the entire access boundary of the embed API — a board is
+         * embeddable because a person said so — and a field a body type does not
+         * name is a field a host's whitelisting `ValidationPipe` deletes. The
+         * failure is silent in the worst direction: the toggle appears to save and
+         * the dashboard is never actually shareable.
+         *
+         * `catalog:curate`: a board carries no SQL of its own, only cards pointing
+         * at queries somebody else vetted. `shared` rides along, which is why the
+         * flag is audited rather than merely stored.
+         */
+        createDashboard(body, request) {
+            return this.service.saveDashboard(body, actorOf(request, body?.createdBy));
         }
         dashboard(id) {
             return this.service.getDashboard(id);
         }
-        patchDashboard(id, body) {
-            return this.service.updateDashboard(id, body);
+        patchDashboard(id, body, request) {
+            return this.service.updateDashboard(id, body, actorOf(request));
         }
-        removeDashboard(id) {
-            return this.service.deleteDashboard(id).then((deleted) => ({ deleted }));
+        /** Deleting a shared board revokes outside access, so the actor is passed. */
+        removeDashboard(id, request) {
+            return this.service.deleteDashboard(id, actorOf(request)).then((deleted) => ({ deleted }));
         }
         /**
          * What this caller may embed.
          *
          * A discovery endpoint so a consuming frontend can list what it is allowed
          * to render rather than being told the ids out of band.
+         *
+         * `catalog:embed` here as well as on the two fetches, and deliberately the
+         * SAME scope rather than a softer one. A caller that cannot fetch anything
+         * has no use for the list, and a discovery endpoint open to callers the
+         * fetches refuse is an inventory of this catalog's shared dashboards handed
+         * to whoever asks.
          */
         embeddable() {
             return this.service.listEmbeddable();
@@ -163,11 +267,26 @@ function createCatalogController(path, guards, decorators = []) {
         embedDashboard(id) {
             return this.service.embedDashboard(id);
         }
-        /** One chart, for a consumer that wants to place it itself. */
+        /**
+         * One chart, for a consumer that wants to place it itself.
+         *
+         * `catalog:embed` and not `catalog:read`: the whole reason the scope exists
+         * separately is that an application rendering one chart in its own UI needs
+         * nothing else, and a route that accepted `catalog:read` instead would make
+         * the narrow grant unusable — every embed consumer would be handed the
+         * whole catalog to draw one bar chart.
+         */
         embedChart(id) {
             return this.service.embedChart(id);
         }
-        /** The audit trail: what happened, to what, by whom. */
+        /**
+         * The audit trail: what happened, to what, by whom.
+         *
+         * `catalog:read`, because attribution here is part of the data rather than a
+         * log — "who loaded these rows" is a question a reader asks months later,
+         * which is the whole reason the principal is recorded onto every snapshot.
+         * The trail carries ids and payloads, never a credential.
+         */
         events(event, typeName, principalId, since, limit) {
             return this.service.listEvents({
                 event,
@@ -216,18 +335,21 @@ function createCatalogController(path, guards, decorators = []) {
     };
     __decorate([
         (0, common_1.Get)(),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "snapshot", null);
     __decorate([
         (0, common_1.Get)('graph'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "graph", null);
     __decorate([
         (0, common_1.Get)('types/:name'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('name')),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [String]),
@@ -235,6 +357,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "type", null);
     __decorate([
         (0, common_1.Patch)('types/:name'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __param(0, (0, common_1.Param)('name')),
         __param(1, (0, common_1.Body)()),
         __metadata("design:type", Function),
@@ -243,6 +366,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "patchType", null);
     __decorate([
         (0, common_1.Patch)('types/:name/properties/:property'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __param(0, (0, common_1.Param)('name')),
         __param(1, (0, common_1.Param)('property')),
         __param(2, (0, common_1.Body)()),
@@ -252,12 +376,14 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "patchProperty", null);
     __decorate([
         (0, common_1.Post)('reset'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", Promise)
     ], CatalogController.prototype, "reset", null);
     __decorate([
         (0, common_1.Get)('objects/:name'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('name')),
         __param(1, (0, common_1.Query)('page')),
         __param(2, (0, common_1.Query)('size')),
@@ -271,12 +397,14 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "objects", null);
     __decorate([
         (0, common_1.Get)('query/relations'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "queryRelations", null);
     __decorate([
         (0, common_1.Post)('query'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:admin'),
         __param(0, (0, common_1.Body)()),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [Object]),
@@ -284,25 +412,30 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "runQuery", null);
     __decorate([
         (0, common_1.Get)('workspace/capabilities'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "workspaceCapabilities", null);
     __decorate([
         (0, common_1.Get)('saved-queries'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "savedQueries", null);
     __decorate([
         (0, common_1.Post)('saved-queries'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:admin'),
         __param(0, (0, common_1.Body)()),
+        __param(1, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [Object]),
+        __metadata("design:paramtypes", [Object, Object]),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "saveSavedQuery", null);
     __decorate([
         (0, common_1.Get)('saved-queries/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('id')),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [String]),
@@ -310,21 +443,26 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "savedQuery", null);
     __decorate([
         (0, common_1.Patch)('saved-queries/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:admin'),
         __param(0, (0, common_1.Param)('id')),
         __param(1, (0, common_1.Body)()),
+        __param(2, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [String, Object]),
+        __metadata("design:paramtypes", [String, Object, Object]),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "patchSavedQuery", null);
     __decorate([
         (0, common_1.Delete)('saved-queries/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __param(0, (0, common_1.Param)('id')),
+        __param(1, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [String]),
+        __metadata("design:paramtypes", [String, Object]),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "removeSavedQuery", null);
     __decorate([
         (0, common_1.Post)('saved-queries/:id/run'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('id')),
         __param(1, (0, common_1.Body)()),
         __metadata("design:type", Function),
@@ -333,6 +471,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "runSavedQuery", null);
     __decorate([
         (0, common_1.Get)('saved-queries/:id/export.csv'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('id')),
         __param(1, (0, common_1.Res)({ passthrough: true })),
         __metadata("design:type", Function),
@@ -341,19 +480,23 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "exportSavedQuery", null);
     __decorate([
         (0, common_1.Get)('dashboards'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "dashboards", null);
     __decorate([
         (0, common_1.Post)('dashboards'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __param(0, (0, common_1.Body)()),
+        __param(1, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [Object]),
+        __metadata("design:paramtypes", [Object, Object]),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "createDashboard", null);
     __decorate([
         (0, common_1.Get)('dashboards/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('id')),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [String]),
@@ -361,27 +504,33 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "dashboard", null);
     __decorate([
         (0, common_1.Patch)('dashboards/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __param(0, (0, common_1.Param)('id')),
         __param(1, (0, common_1.Body)()),
+        __param(2, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [String, Object]),
+        __metadata("design:paramtypes", [String, Object, Object]),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "patchDashboard", null);
     __decorate([
         (0, common_1.Delete)('dashboards/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __param(0, (0, common_1.Param)('id')),
+        __param(1, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [String]),
+        __metadata("design:paramtypes", [String, Object]),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "removeDashboard", null);
     __decorate([
         (0, common_1.Get)('embed'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:embed'),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", []),
         __metadata("design:returntype", void 0)
     ], CatalogController.prototype, "embeddable", null);
     __decorate([
         (0, common_1.Get)('embed/dashboards/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:embed'),
         __param(0, (0, common_1.Param)('id')),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [String]),
@@ -389,6 +538,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "embedDashboard", null);
     __decorate([
         (0, common_1.Get)('embed/charts/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:embed'),
         __param(0, (0, common_1.Param)('id')),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [String]),
@@ -396,6 +546,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "embedChart", null);
     __decorate([
         (0, common_1.Get)('events'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Query)('event')),
         __param(1, (0, common_1.Query)('type')),
         __param(2, (0, common_1.Query)('principal')),
@@ -407,6 +558,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "events", null);
     __decorate([
         (0, common_1.Get)('events/traces'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Query)('type')),
         __param(1, (0, common_1.Query)('principal')),
         __param(2, (0, common_1.Query)('event')),
@@ -420,6 +572,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "traceList", null);
     __decorate([
         (0, common_1.Get)('events/traces/:id'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('id')),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [String]),
@@ -427,6 +580,7 @@ function createCatalogController(path, guards, decorators = []) {
     ], CatalogController.prototype, "trace", null);
     __decorate([
         (0, common_1.Get)('objects/:name/snapshots'),
+        (0, catalog_route_auth_1.RequireScopes)('catalog:read'),
         __param(0, (0, common_1.Param)('name')),
         __metadata("design:type", Function),
         __metadata("design:paramtypes", [String]),
@@ -447,6 +601,28 @@ function createCatalogController(path, guards, decorators = []) {
     }
     return CatalogController;
 }
+/**
+ * Who to record a workspace change against.
+ *
+ * The host's resolved principal wins over anything the body claimed, and that
+ * order is the whole point: a `createdBy` in a request body is a name the caller
+ * chose for itself, and letting it beat the principal a guard authenticated
+ * would make the audit trail's actor column a free-text field. It is still
+ * honoured when there is no principal, because this library does not resolve
+ * one — see the enforcement note in `catalog.principal.ts` — and a host that has
+ * not wired a guard yet is better served by "console" than by nothing.
+ *
+ * `principal.id` rather than `applicationId`, matching every other event on this
+ * channel: for a delegated caller that string carries the person inside it, and
+ * dropping to the application half would attribute a person's decision to the
+ * console they used.
+ */
+function actorOf(request, claimed) {
+    const resolved = request?.principal?.id?.trim();
+    if (resolved)
+        return resolved;
+    return claimed?.trim() || 'console';
+}
 /**
  * `?outcome=failed`, `?outcome=failed,incomplete`, `?outcome=a&outcome=b`.
  *

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) => {