@dudousxd/nestjs-catalog 0.5.0 → 0.6.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.environment.d.ts

@@ -94,13 +94,24 @@ export interface CatalogEnvironment {
      */
     rank: number;
     /**
-     * Whether this environment refuses changes that did not arrive as a reviewed
-     * promotion.
+     * A declaration that this environment is one where changes are supposed to
+     * arrive as a reviewed promotion. True for production.
      *
-     * True for production. It does not lock the environment — an operator can
-     * still fix something by hand — it means the API demands the explicit
-     * confirmation described on {@link CatalogPromotionApproval} rather than
-     * accepting a plan somebody generated in another tab ten minutes ago.
+     * **Advisory. Nothing in this library refuses anything because of it.** No
+     * guard, no store and no plan reads this field; the only code that does is the
+     * console, which paints the environment switcher amber so that "am I about to
+     * do this to production" is answerable at a glance. That is worth having and
+     * it is worth not overstating — a flag documented as an enforcement point,
+     * enforced nowhere, is worse than no flag, because it invites a host to
+     * believe the refusal already exists.
+     *
+     * Kept rather than removed because the enforcement it describes cannot live
+     * here. The library has no apply endpoint and no opinion about who may approve
+     * what — see {@link CatalogPromotionPlan.fingerprint} for the same division —
+     * so the refusal belongs to whatever host exposes promotion over HTTP. This
+     * field is how that host learns which environments to demand
+     * {@link CatalogPromotionApproval} for, without every deployment restating its
+     * own list of environment names in a guard.
      */
     protected: boolean;
 }
@@ -173,17 +184,40 @@ export declare function catalogDatabaseNameFor(base: string, environmentId: Cata
  * It stops being enough the moment anyone asks a governance question across
  * environments — "everything this person did this week" has to be answerable
  * without the reader having to remember which of three lists they are looking
- * at — so the environment is stamped onto every event as it leaves its store.
+ * at.
  *
  * Stamped on read rather than stored in a column on purpose: a stored column
  * can be wrong, because nothing in the database stops a row in the production
  * table saying `environment: "dev"`. A value derived from which connection the
  * row was read through cannot be.
+ *
+ * Which is also why the stamping does not happen here, and cannot. This package
+ * knows what an environment *is*; it has no connection and no scope, so it can
+ * only supply the shape and the function. The stamp is applied by the one reader
+ * that resolved an environment in order to do the read at all —
+ * `RoutingWorkspaceStore.listEvents` in the MikroORM store package, which widens
+ * its return type to this intersection. A read that went straight to a store,
+ * with no environment resolved anywhere above it, is *not* stamped, and that is
+ * the honest answer rather than a gap: nothing in that call knew which world it
+ * was reading, so anything written into the field would be a guess.
  */
 export interface EnvironmentStampedAuditEvent {
     environment: CatalogEnvironmentId;
 }
-/** Stamps a batch of events with the environment they were read from. */
+/**
+ * Stamps a batch of events with the environment they were read from.
+ *
+ * A separate function taking the id as an argument rather than a method
+ * somewhere, so the caller has to have the environment in hand to call it. There
+ * is no default and nothing to look up — the id comes from the same resolution
+ * that chose the connection, which is what makes the stamp a fact about the read
+ * rather than a label somebody attached afterwards.
+ *
+ * Generic over the event rather than typed to `CatalogAuditEvent`, which lives
+ * in `catalog.workspace.ts` and would make this file depend on the workspace
+ * vocabulary to say something true of any row. Nothing here needs to know more
+ * about an event than that it is an object.
+ */
 export declare function stampEnvironment<T>(environment: CatalogEnvironmentId, events: readonly T[]): Array<T & EnvironmentStampedAuditEvent>;
 /** What a promotion is allowed to carry. */
 export declare const PROMOTABLE_KINDS: readonly ["objectType", "transform", "workflow", "connector"];
@@ -375,9 +409,22 @@ export interface CatalogPromotionPlan {
      * The point of a preview is that somebody read it. Without a fingerprint the
      * apply call is a fresh promotion that happens to have been preceded by a
      * preview, and anything that changed in between — a colleague editing the
-     * transform, a connector deleted — goes in unreviewed. The apply endpoint
-     * demands this value back, recomputes the plan, and refuses if the two
-     * differ. That is what turns "we show a diff" into "you approved this diff".
+     * transform, a connector deleted — goes in unreviewed.
+     *
+     * **The check is the host's, and this library does not perform it.** There is
+     * no apply endpoint here: `applyPromotion` is exported for a host to call, and
+     * it does not recompute the plan or compare anything to this value. The
+     * expectation, stated the same way where the apply lives, is that the caller
+     * re-runs {@link planPromotion} immediately before applying and confirms the
+     * fingerprint still matches what the reviewer approved. It lives with the
+     * caller because it is a policy decision about who may approve what, and
+     * `applyPromotion` is the mechanism rather than the policy.
+     *
+     * So this field is what makes that check *possible* — a stable name for one
+     * reviewed set of changes, computed from the effect and not the clock — and
+     * not, on its own, the check. A host that carries the value from preview to
+     * apply and never compares it has a promotion nobody approved, and nothing in
+     * this package will say so.
      */
     fingerprint: string;
 }
@@ -394,7 +441,13 @@ export interface CatalogPromotionPlan {
  * which environment the row belongs to.
  */
 export declare const PROMOTION_AUDIT_EVENT = "promotion.applied";
-/** What an apply call must present to prove which plan was approved. */
+/**
+ * What a host's apply call asks for, to prove which plan was approved.
+ *
+ * A shape rather than a check — see {@link CatalogPromotionPlan.fingerprint} for
+ * why the comparison lives with the caller. Written down here so that every host
+ * demands the same two things and an audit row means the same thing in each.
+ */
 export interface CatalogPromotionApproval {
     fingerprint: string;
     /** Free text the operator typed. Recorded in the audit trail, never parsed. */

package/dist/catalog.environment.js

@@ -216,7 +216,20 @@ function durableKeyspaceFor(environmentId, prefix = 'catalog') {
 function catalogDatabaseNameFor(base, environmentId) {
     return `${base}_${assertEnvironmentId(environmentId)}`;
 }
-/** Stamps a batch of events with the environment they were read from. */
+/**
+ * Stamps a batch of events with the environment they were read from.
+ *
+ * A separate function taking the id as an argument rather than a method
+ * somewhere, so the caller has to have the environment in hand to call it. There
+ * is no default and nothing to look up — the id comes from the same resolution
+ * that chose the connection, which is what makes the stamp a fact about the read
+ * rather than a label somebody attached afterwards.
+ *
+ * Generic over the event rather than typed to `CatalogAuditEvent`, which lives
+ * in `catalog.workspace.ts` and would make this file depend on the workspace
+ * vocabulary to say something true of any row. Nothing here needs to know more
+ * about an event than that it is an object.
+ */
 function stampEnvironment(environment, events) {
     return events.map((event) => ({ ...event, environment }));
 }