@dudousxd/nestjs-catalog 0.9.0 → 0.10.0

package/dist/catalog.controller.js

@@ -148,24 +148,44 @@ function createCatalogController(path, guards, decorators = []) {
         /**
          * Tier 0. Renames a type, regroups it, changes its icon. No migration, no
          * deploy, no engineer.
+         *
+         * The principal is passed for the reason the sharing routes below pass one:
+         * a curated label outlives the publisher's next deploy, so "who renamed this
+         * column" is asked long after any log has rotated. `actorOf` and not
+         * `request.principal.id` directly, so an unguarded mount records `console`
+         * rather than an empty actor — see the note on it.
+         *
+         * The body deliberately names no `createdBy`-style override, unlike the
+         * saved-query create route. Nothing here stores an author; the only consumer
+         * of the name is the audit entry, and a caller that can write any string into
+         * the trail's actor column is worse than one recorded as the console.
          */
-        async patchType(name, body) {
-            const updated = await this.registry.patchType(name, body);
+        async patchType(name, body, request) {
+            const updated = await this.registry.patchType(name, body, actorOf(request));
             if (!updated)
                 throw new common_1.NotFoundException(`Unknown object type: ${name}`);
             return updated;
         }
         /** Tier 0, one property at a time. */
-        async patchProperty(name, property, body) {
-            const updated = await this.registry.patchProperty(name, property, body);
+        async patchProperty(name, property, body, request) {
+            const updated = await this.registry.patchProperty(name, property, body, actorOf(request));
             if (!updated) {
                 throw new common_1.NotFoundException(`Unknown property: ${name}.${property}`);
             }
             return updated;
         }
-        /** Drops every tier-0 edit and falls back to what the ORM says. */
-        async reset() {
-            await this.registry.resetOverlay();
+        /**
+         * Drops every tier-0 edit and falls back to what the ORM says.
+         *
+         * The actor matters most here of the three. This destroys every curated
+         * label, unit and **classification** in the catalog in one request, under the
+         * same `catalog:curate` a rename needs — and un-classifying a property
+         * re-admits its name to searches by principals who could not see it an
+         * instant earlier. Nothing versions the overlay, so after this the only
+         * record that it happened, and of who did it, is the event.
+         */
+        async reset(request) {
+            await this.registry.resetOverlay(actorOf(request));
             return this.registry.getSnapshot();
         }
         /** One generic read endpoint for every type in the catalog. */
@@ -414,8 +434,9 @@ function createCatalogController(path, guards, decorators = []) {
         (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
         __param(0, (0, common_1.Param)('name')),
         __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", Promise)
     ], CatalogController.prototype, "patchType", null);
     __decorate([
@@ -424,15 +445,17 @@ function createCatalogController(path, guards, decorators = []) {
         __param(0, (0, common_1.Param)('name')),
         __param(1, (0, common_1.Param)('property')),
         __param(2, (0, common_1.Body)()),
+        __param(3, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", [String, String, Object]),
+        __metadata("design:paramtypes", [String, String, Object, Object]),
         __metadata("design:returntype", Promise)
     ], CatalogController.prototype, "patchProperty", null);
     __decorate([
         (0, common_1.Post)('reset'),
         (0, catalog_route_auth_1.RequireScopes)('catalog:curate'),
+        __param(0, (0, common_1.Req)()),
         __metadata("design:type", Function),
-        __metadata("design:paramtypes", []),
+        __metadata("design:paramtypes", [Object]),
         __metadata("design:returntype", Promise)
     ], CatalogController.prototype, "reset", null);
     __decorate([
@@ -656,7 +679,12 @@ function createCatalogController(path, guards, decorators = []) {
     return CatalogController;
 }
 /**
- * Who to record a workspace change against.
+ * Who to record a change against — a workspace one, and now a curation one.
+ *
+ * Shared by both on purpose. The two halves of the trail used to answer the "who"
+ * question differently: sharing named its principal and curation named nobody at
+ * all, which reads as a bug in whichever half you look at second. One helper is
+ * what keeps the two from drifting again, including on the fallback below.
  *
  * 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

package/dist/catalog.events.d.ts

@@ -44,6 +44,41 @@ export declare const CATALOG_EVENT_PHASE: Record<CatalogEvent, number>;
  */
 export declare const CATALOG_EVENT_PHASE_FALLBACK = 4;
 export declare function catalogEventPhase(event: string): number;
+/**
+ * What a curation entry says when nothing told it who.
+ *
+ * A value rather than an empty string or a missing key, and that difference is
+ * the whole reason it exists. The shipped recorder writes
+ * `principalId: undefined` for anything falsy, which lands as NULL in the column
+ * every governance query filters on — and a NULL there is indistinguishable from
+ * the rows written before this library recorded actors at all. "Not captured"
+ * and "nobody did this" are different statements, and only the first one is true.
+ *
+ * Deliberately not the same string as the controller's `console` fallback, which
+ * is a narrower and more useful claim: `console` says a request came through
+ * this library's own HTTP surface and no guard resolved a principal onto it —
+ * the deployment has an unauthenticated mount. This one says the registry API
+ * was called in-process and the caller named nobody: a host script, a scheduled
+ * job, or a subclass compiled against the signature before it took an actor.
+ * Collapsing them would throw away the only clue about where to go looking, in
+ * exchange for one fewer constant.
+ */
+export declare const UNATTRIBUTED_PRINCIPAL_ID = "unattributed";
+/**
+ * The actor a curation event will carry, given whatever the caller passed.
+ *
+ * Exported because both registries need it and they ship in different packages —
+ * the in-app one here, the stored one in `store-mikro-orm` — so a copy each is a
+ * rule that holds in two places right up until it holds in one.
+ *
+ * Total, and it re-checks a parameter the types already made required. That is
+ * not belt-and-braces: `CatalogRegistry` binds TypeScript callers, and the
+ * callers whose omission must never reach the trail are precisely the ones it
+ * does not bind — a JavaScript host, and a subclass declaring the older
+ * argument list, which stays a legal override because TypeScript lets an
+ * implementation take fewer parameters than it promised.
+ */
+export declare function curationActor(principalId: string | undefined): string;
 export interface CatalogEventPayloads {
     /** DDL was applied to an object type's physical table. Always additive. */
     'schema.changed': {
@@ -80,6 +115,38 @@ export interface CatalogEventPayloads {
         typeName: string;
         property?: string;
         changed: string[];
+        /**
+         * Who renamed it — the half of that sentence this payload used to leave out.
+         *
+         * It carried `typeName`, `property` and `changed`, which answers "what" and
+         * (with the row's timestamp) "when", and never "who" — while `query.shared`
+         * two screens away named its actor from the day it was added. An audit trail
+         * that is inconsistent about attribution reads as broken in whichever half
+         * you look at second, and curation is the side where it matters more:
+         * a curated label is the one decision this library describes as surviving
+         * the publisher's next deploy.
+         *
+         * **`principalId`, not `curatedBy`,** because the spelling is a contract with
+         * a recorder this package cannot import. `CatalogAuditRecorder` lifts exactly
+         * this key into the audit table's indexed column; a payload that names it
+         * anything else still carries the actor, in a JSON blob no query anybody runs
+         * will look inside, and the entry lands attributed to nobody while looking
+         * complete.
+         *
+         * **The whole `CatalogPrincipal.id`, composite half included.** The same
+         * choice `query.shared` made, for the reason `catalog.principal.ts` argues at
+         * length: `parsePrincipalId` recovers the application from an
+         * `<app>#<person>` id, so carrying the person costs the machine-level
+         * question nothing — while dropping to `applicationId` would file a curator's
+         * decision under the console they happened to sign into, and "the console
+         * renamed this column" is the answer that file says nobody accepts.
+         *
+         * **Required, and never the empty string.** The recorder treats a falsy value
+         * as absent and writes NULL, which reads as "nobody did this" rather than
+         * "this was not captured". A producer holding no principal emits
+         * {@link UNATTRIBUTED_PRINCIPAL_ID} instead, which is a statement.
+         */
+        principalId: string;
     };
     /**
      * The whole overlay was discarded — every curated label, description, unit,
@@ -123,20 +190,24 @@ export interface CatalogEventPayloads {
      *   to whom, they are a small subset of it, and re-typing them is the only
      *   recovery anybody can perform.
      *
-     * **No `principalId`, and the absence is a limit rather than a decision that
-     * the actor does not matter.** `resetOverlay()` takes no principal, the route
-     * that calls it resolves none, and `RoutingCatalogRegistry` forwards the call
-     * by hand — so a field here would be `undefined` on every row, and an audit
-     * table lifts `principalId` into a column where empty reads as "nobody did
-     * this" rather than "this was not captured". `type.curated` has the same gap.
-     * Closing it means threading a principal through the controller, the service
-     * and every registry, which is a change to those, not a field on this payload.
+     * **It carries `principalId`, which it did not at first**, and the reason the
+     * gap existed is worth keeping: `resetOverlay()` took no principal, the route
+     * resolved none for it, and `RoutingCatalogRegistry` forwards the call by hand,
+     * so a field here would have been empty on every row — and an audit table
+     * lifts `principalId` into a column where empty reads as "nobody did this"
+     * rather than "this was not captured". The answer was to thread the actor
+     * through all three rather than to keep documenting its absence, because this
+     * is the one act on the catalog that destroys decisions in bulk and needs only
+     * `catalog:curate` to do it. See `type.curated` above for what the field holds
+     * and why it is spelled that way.
      *
      * Emitted even when the overlay was empty, with zeroes. A trail that recorded
      * only destructive resets cannot tell "nobody pressed it" from "somebody
      * pressed it and nothing was there", and the second is worth seeing.
      */
     'overlay.reset': {
+        /** Who reverted the catalog. See `type.curated`'s `principalId`. */
+        principalId: string;
         /** Every type that carried curation, so the trail names what was lost. */
         typeNames: string[];
         /** How many per-property entries went with them, across every type. */

package/dist/catalog.events.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CATALOG_EVENTS = exports.CATALOG_LIB = void 0;
+exports.UNATTRIBUTED_PRINCIPAL_ID = exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CATALOG_EVENTS = exports.CATALOG_LIB = void 0;
 exports.catalogEventPhase = catalogEventPhase;
+exports.curationActor = curationActor;
 exports.channelNameFor = channelNameFor;
 exports.emitCatalog = emitCatalog;
 const nestjs_diagnostics_1 = require("@dudousxd/nestjs-diagnostics");
@@ -102,6 +103,44 @@ function catalogEventPhase(event) {
     const phase = Reflect.get(exports.CATALOG_EVENT_PHASE, event);
     return typeof phase === 'number' ? phase : exports.CATALOG_EVENT_PHASE_FALLBACK;
 }
+/**
+ * What a curation entry says when nothing told it who.
+ *
+ * A value rather than an empty string or a missing key, and that difference is
+ * the whole reason it exists. The shipped recorder writes
+ * `principalId: undefined` for anything falsy, which lands as NULL in the column
+ * every governance query filters on — and a NULL there is indistinguishable from
+ * the rows written before this library recorded actors at all. "Not captured"
+ * and "nobody did this" are different statements, and only the first one is true.
+ *
+ * Deliberately not the same string as the controller's `console` fallback, which
+ * is a narrower and more useful claim: `console` says a request came through
+ * this library's own HTTP surface and no guard resolved a principal onto it —
+ * the deployment has an unauthenticated mount. This one says the registry API
+ * was called in-process and the caller named nobody: a host script, a scheduled
+ * job, or a subclass compiled against the signature before it took an actor.
+ * Collapsing them would throw away the only clue about where to go looking, in
+ * exchange for one fewer constant.
+ */
+exports.UNATTRIBUTED_PRINCIPAL_ID = 'unattributed';
+/**
+ * The actor a curation event will carry, given whatever the caller passed.
+ *
+ * Exported because both registries need it and they ship in different packages —
+ * the in-app one here, the stored one in `store-mikro-orm` — so a copy each is a
+ * rule that holds in two places right up until it holds in one.
+ *
+ * Total, and it re-checks a parameter the types already made required. That is
+ * not belt-and-braces: `CatalogRegistry` binds TypeScript callers, and the
+ * callers whose omission must never reach the trail are precisely the ones it
+ * does not bind — a JavaScript host, and a subclass declaring the older
+ * argument list, which stays a legal override because TypeScript lets an
+ * implementation take fewer parameters than it promised.
+ */
+function curationActor(principalId) {
+    const trimmed = typeof principalId === 'string' ? principalId.trim() : '';
+    return trimmed.length > 0 ? trimmed : exports.UNATTRIBUTED_PRINCIPAL_ID;
+}
 /**
  * The channel an event is published on.
  *

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

@@ -38,6 +38,35 @@ export declare class FileCatalogOverlayStore implements CatalogOverlayStore {
  * turn a policy answer ("you may not curate here") into a 500 from a route the
  * library documents as working, and would put a second mechanism beside the one
  * that already decides.
+ *
+ * **Both ends copy, and one end would not have been enough.** The registry holds
+ * the overlay it loaded and edits it in place — `this.overlay.types[name] = {
+ * ...current, ...patch }` — before calling `save`. Copy only on `load` and the
+ * object handed to `save` becomes the store's own, so the next patch is writing
+ * into the store again; copy only on `save` and the object handed out by `load`
+ * already is the store's own. Either way this store's state moves before
+ * anybody asked it to, and "nothing is stored until save" — the one sentence a
+ * store is for — is not true of it.
+ *
+ * That mattered in two directions, neither of them the net behaviour, which was
+ * and is identical because every edit is followed by a persist.
+ *
+ * - **The two bundled stores disagreed.** {@link FileCatalogOverlayStore}
+ *   round-trips through JSON and so has never aliased anything. Every spec in
+ *   this repository runs on this one, so a test asserting that an edit had not
+ *   been written yet passed here and would have failed on the store a
+ *   deployment actually uses. A vacuous pass is worse than no test: it is a
+ *   claim with evidence attached to it.
+ * - **Two registries over one store shared mutable state.** One would see the
+ *   other's half-applied edit with no write between them, which is the shape
+ *   that produces a report nobody can reproduce.
+ *
+ * **What it costs.** One deep copy per load and per save. The overlay is the
+ * names, descriptions and per-property patches a human has typed — not the
+ * catalog, which is derived from entity metadata and does not live here — so a
+ * heavily curated thousand-type catalog is a few hundred kilobytes and a copy
+ * in the low milliseconds. The two paths that pay it are a boot and a curator
+ * pressing save. Neither is a read, and nothing on a request path calls either.
  */
 export declare class InMemoryCatalogOverlayStore implements CatalogOverlayStore {
     private overlay;

package/dist/catalog.overlay-store.js

@@ -55,17 +55,60 @@ exports.FileCatalogOverlayStore = FileCatalogOverlayStore;
  * turn a policy answer ("you may not curate here") into a 500 from a route the
  * library documents as working, and would put a second mechanism beside the one
  * that already decides.
+ *
+ * **Both ends copy, and one end would not have been enough.** The registry holds
+ * the overlay it loaded and edits it in place — `this.overlay.types[name] = {
+ * ...current, ...patch }` — before calling `save`. Copy only on `load` and the
+ * object handed to `save` becomes the store's own, so the next patch is writing
+ * into the store again; copy only on `save` and the object handed out by `load`
+ * already is the store's own. Either way this store's state moves before
+ * anybody asked it to, and "nothing is stored until save" — the one sentence a
+ * store is for — is not true of it.
+ *
+ * That mattered in two directions, neither of them the net behaviour, which was
+ * and is identical because every edit is followed by a persist.
+ *
+ * - **The two bundled stores disagreed.** {@link FileCatalogOverlayStore}
+ *   round-trips through JSON and so has never aliased anything. Every spec in
+ *   this repository runs on this one, so a test asserting that an edit had not
+ *   been written yet passed here and would have failed on the store a
+ *   deployment actually uses. A vacuous pass is worse than no test: it is a
+ *   claim with evidence attached to it.
+ * - **Two registries over one store shared mutable state.** One would see the
+ *   other's half-applied edit with no write between them, which is the shape
+ *   that produces a report nobody can reproduce.
+ *
+ * **What it costs.** One deep copy per load and per save. The overlay is the
+ * names, descriptions and per-property patches a human has typed — not the
+ * catalog, which is derived from entity metadata and does not live here — so a
+ * heavily curated thousand-type catalog is a few hundred kilobytes and a copy
+ * in the low milliseconds. The two paths that pay it are a boot and a curator
+ * pressing save. Neither is a read, and nothing on a request path calls either.
  */
 class InMemoryCatalogOverlayStore {
     overlay = { types: {} };
     async load() {
-        return this.overlay;
+        return copyOverlay(this.overlay);
     }
     async save(overlay) {
-        this.overlay = overlay;
+        this.overlay = copyOverlay(overlay);
     }
 }
 exports.InMemoryCatalogOverlayStore = InMemoryCatalogOverlayStore;
+/**
+ * A deep copy, so a caller and the store never hold one object between them.
+ *
+ * `structuredClone` rather than a `JSON.parse(JSON.stringify(...))` round-trip,
+ * which differs on a key whose value is `undefined`: JSON drops it, so
+ * `{ displayName: undefined }` comes back as `{}` and `'displayName' in entry`
+ * flips from true to false. Nothing reads the overlay that way today. A copy
+ * that quietly edits what it copies is still not a copy, and the day something
+ * does read it that way the difference is a curated field that vanished with no
+ * write behind it.
+ */
+function copyOverlay(overlay) {
+    return structuredClone(overlay);
+}
 /**
  * Whether a parsed file is an overlay, checked to the depth that matters.
  *

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

@@ -59,9 +59,14 @@ export declare abstract class CatalogRegistry {
      * 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>;
+    /**
+     * Presentation-only edits. Never a schema change.
+     *
+     * @param curatedBy the acting principal's id, recorded on `type.curated`.
+     */
+    abstract patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>, curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
+    /** @param curatedBy the acting principal's id, recorded on `type.curated`. */
+    abstract patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string], curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
     /**
      * Discard every tier-0 edit at once.
      *
@@ -81,6 +86,12 @@ export declare abstract class CatalogRegistry {
      * Which of those a deployment runs is why the event is worth more than the
      * call it accompanies: a registry that quietly resets without emitting looks
      * exactly like one that never ran a reset at all.
+     *
+     * @param resetBy the acting principal's id, recorded on `overlay.reset`. An
+     * implementation that refuses is free to declare no parameter at all — an
+     * override may take fewer than it was promised — and `StoredCatalogRegistry`
+     * does, because an argument it accepted and never recorded would read as a
+     * dropped actor rather than as a reset that never happened.
      */
-    abstract resetOverlay(): Promise<void>;
+    abstract resetOverlay(resetBy: string): Promise<void>;
 }

package/dist/catalog.registry.d.ts

@@ -32,9 +32,9 @@ export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements
      */
     getEntityClass(name: string): EntityClass<Record<string, unknown>> | undefined;
     /** Tier-0 edit on a type. Never touches the database. */
-    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
+    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>, curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
     /** Tier-0 edit on a property. Never touches the database. */
-    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
+    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string], curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
     /**
      * Drop every tier-0 edit, and leave a record that it happened.
      *
@@ -45,8 +45,14 @@ export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements
      *
      * Emitted after the write, like the two patches above, so the trail says what
      * happened rather than what was about to.
+     *
+     * The actor is applied here rather than inside {@link summariseOverlay}, which
+     * stays a pure function of the overlay. What was destroyed and who destroyed it
+     * are facts from two different places, and folding the principal into the
+     * summariser would mean the one function that must be callable with nothing but
+     * an old overlay suddenly needing the request as well.
      */
-    resetOverlay(): Promise<void>;
+    resetOverlay(resetBy: string): Promise<void>;
     private persist;
     private rebuild;
     private shouldInclude;

package/dist/catalog.registry.js

@@ -179,7 +179,7 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
         return this.entityClasses.get(name);
     }
     /** Tier-0 edit on a type. Never touches the database. */
-    async patchType(typeName, patch) {
+    async patchType(typeName, patch, curatedBy) {
         const type = this.getType(typeName);
         if (!type)
             return undefined;
@@ -192,11 +192,15 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
         (0, catalog_events_1.emitCatalog)('type.curated', {
             typeName: type.name,
             changed: Object.keys(rest),
+            // Through `curationActor` rather than passed straight in, even though the
+            // parameter is required: the callers this class actually has to survive are
+            // the ones the compiler never saw. See the note on that function.
+            principalId: (0, catalog_events_1.curationActor)(curatedBy),
         });
         return this.getType(type.name);
     }
     /** Tier-0 edit on a property. Never touches the database. */
-    async patchProperty(typeName, propertyName, patch) {
+    async patchProperty(typeName, propertyName, patch, curatedBy) {
         const type = this.getType(typeName);
         if (!type)
             return undefined;
@@ -218,6 +222,7 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             typeName: type.name,
             property: propertyName,
             changed: Object.keys(patch),
+            principalId: (0, catalog_events_1.curationActor)(curatedBy),
         });
         return this.getType(type.name);
     }
@@ -231,12 +236,18 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
      *
      * Emitted after the write, like the two patches above, so the trail says what
      * happened rather than what was about to.
+     *
+     * The actor is applied here rather than inside {@link summariseOverlay}, which
+     * stays a pure function of the overlay. What was destroyed and who destroyed it
+     * are facts from two different places, and folding the principal into the
+     * summariser would mean the one function that must be callable with nothing but
+     * an old overlay suddenly needing the request as well.
      */
-    async resetOverlay() {
+    async resetOverlay(resetBy) {
         const discarded = summariseOverlay(this.overlay);
         this.overlay = { types: {} };
         await this.persist();
-        (0, catalog_events_1.emitCatalog)('overlay.reset', discarded);
+        (0, catalog_events_1.emitCatalog)('overlay.reset', { ...discarded, principalId: (0, catalog_events_1.curationActor)(resetBy) });
     }
     async persist() {
         await this.overlayStore.save(this.overlay);
@@ -390,6 +401,13 @@ exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegis
  * order is forced: a caller has to hold the old overlay to call it, and cannot
  * accidentally summarise the empty one it just installed.
  *
+ * Everything the payload holds except the actor, stated as an `Omit` of the
+ * payload rather than a shape of its own. A hand-written interface here would be
+ * a second copy of the contract, free to fall behind the day a field is added —
+ * and the failure would be a summary silently missing a key that the type says
+ * is required. `principalId` is the caller's to supply because it is a fact about
+ * the request, not about the overlay.
+ *
  * A type entry counts whatever it holds, including an entry that ended up empty.
  * `buildType` treats a present entry as enrichment on the same terms, and the
  * honest reading of one is "somebody patched this type" — which is exactly what

package/dist/catalog.service.d.ts

@@ -27,11 +27,26 @@ export declare class CatalogService {
     getType(name: string): CatalogObjectTypeDef | undefined;
     /** Nodes and edges, for drawing the model. */
     getGraph(): CatalogGraph;
-    /** Presentation-only. Never a schema change. */
-    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
-    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
-    /** Drops every runtime edit, where the registry supports it. */
-    resetOverlay(): Promise<void>;
+    /**
+     * Presentation-only. Never a schema change.
+     *
+     * @param curatedBy who is doing it, for the audit trail — the same required
+     * argument the sharing methods below take, and required for the same reason
+     * `deleteSavedQuery` gives. This facade forwards it rather than resolving it:
+     * a host writing its own controller has the request and this does not, and a
+     * default here would attribute every such host's curation to nobody.
+     */
+    patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>, curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
+    /** @param curatedBy who is doing it, for the audit trail. */
+    patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string], curatedBy: string): Promise<CatalogObjectTypeDef | undefined>;
+    /**
+     * Drops every runtime edit, where the registry supports it.
+     *
+     * @param resetBy who is doing it. The one act here that destroys curation in
+     * bulk, so it is the one whose actor is hardest to reconstruct afterwards —
+     * nothing versions an overlay, and after this there is nothing left to read.
+     */
+    resetOverlay(resetBy: string): Promise<void>;
     /** Columns a generic UI may render: visible, and not a blob. */
     visibleColumns(type: CatalogObjectTypeDef): import("./catalog.types").CatalogPropertyDef[];
     /**

package/dist/catalog.service.js

@@ -66,16 +66,31 @@ let CatalogService = class CatalogService {
     getGraph() {
         return this.registry.getGraph();
     }
-    /** Presentation-only. Never a schema change. */
-    patchType(typeName, patch) {
-        return this.registry.patchType(typeName, patch);
+    /**
+     * Presentation-only. Never a schema change.
+     *
+     * @param curatedBy who is doing it, for the audit trail — the same required
+     * argument the sharing methods below take, and required for the same reason
+     * `deleteSavedQuery` gives. This facade forwards it rather than resolving it:
+     * a host writing its own controller has the request and this does not, and a
+     * default here would attribute every such host's curation to nobody.
+     */
+    patchType(typeName, patch, curatedBy) {
+        return this.registry.patchType(typeName, patch, curatedBy);
     }
-    patchProperty(typeName, propertyName, patch) {
-        return this.registry.patchProperty(typeName, propertyName, patch);
+    /** @param curatedBy who is doing it, for the audit trail. */
+    patchProperty(typeName, propertyName, patch, curatedBy) {
+        return this.registry.patchProperty(typeName, propertyName, patch, curatedBy);
     }
-    /** Drops every runtime edit, where the registry supports it. */
-    resetOverlay() {
-        return this.registry.resetOverlay();
+    /**
+     * Drops every runtime edit, where the registry supports it.
+     *
+     * @param resetBy who is doing it. The one act here that destroys curation in
+     * bulk, so it is the one whose actor is hardest to reconstruct afterwards —
+     * nothing versions an overlay, and after this there is nothing left to read.
+     */
+    resetOverlay(resetBy) {
+        return this.registry.resetOverlay(resetBy);
     }
     /** Columns a generic UI may render: visible, and not a blob. */
     visibleColumns(type) {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { CatalogProperty, type CatalogPropertyOptions, CatalogType, type CatalogTypeOptions, } from './catalog.decorators';
-export { CATALOG_EVENT_PHASE, CATALOG_EVENT_PHASE_FALLBACK, CATALOG_EVENTS, CATALOG_LIB, type CatalogEvent, type CatalogEventPayloads, catalogEventPhase, channelNameFor, emitCatalog, } from './catalog.events';
+export { CATALOG_EVENT_PHASE, CATALOG_EVENT_PHASE_FALLBACK, CATALOG_EVENTS, CATALOG_LIB, type CatalogEvent, type CatalogEventPayloads, UNATTRIBUTED_PRINCIPAL_ID, catalogEventPhase, channelNameFor, curationActor, emitCatalog, } from './catalog.events';
 export { CatalogModule } from './catalog.module';
 export { assertReadOnlyShape, type CatalogQueryRelation, type CatalogQueryRequest, type CatalogQueryResult, type CatalogQueryStore, isQueryStore, } from './catalog.query';
 export { CATALOG_OPTIONS, type CatalogModuleOptions } from './catalog.options';

package/dist/index.js

@@ -14,8 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_TRACE_OUTCOMES = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = exports.emptySearch = exports.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.TRANSFORM_RUNNER = exports.supportsWorkflowStages = exports.supportsWorkflows = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isPipelineStore = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.CATALOG_PIPELINE_STORE = exports.CatalogRegistry = exports.MikroOrmCatalogRegistry = exports.CATALOG_OVERLAY_STORE = exports.InMemoryCatalogOverlayStore = exports.FileCatalogOverlayStore = exports.CATALOG_OPTIONS = exports.isQueryStore = exports.assertReadOnlyShape = exports.CatalogModule = exports.emitCatalog = exports.channelNameFor = exports.catalogEventPhase = exports.CATALOG_LIB = exports.CATALOG_EVENTS = exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CatalogType = exports.CatalogProperty = void 0;
-exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.MikroOrmReadStore = exports.supportsCarryForward = exports.isWriteStore = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = exports.CATALOG_RESERVED_COLUMNS = exports.assertNoColumnCollisions = exports.StaticKeyPrincipalResolver = exports.readableObjectPage = exports.mayWrite = exports.mayRead = exports.maySeeClassification = exports.PRINCIPAL_ACTOR_SEPARATOR = exports.parsePrincipalId = exports.hasScope = exports.expandScopes = exports.delegatePrincipal = exports.composePrincipalId = exports.CATALOG_PRINCIPAL_RESOLVER = exports.traceOutcomeFilter = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = void 0;
+exports.searchCatalog = exports.maySearch = exports.emptySearch = exports.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.SubprocessTransformRunner = exports.toCsv = exports.QueryCache = exports.workflowRunOrder = exports.workflowGraphHash = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.validateWorkflow = exports.TRANSFORM_LANGUAGES = exports.TRANSFORM_RUNNER = exports.supportsWorkflowStages = exports.supportsWorkflows = exports.isWorkflowNodeKind = exports.isWorkflowNode = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.isTransformLanguage = exports.isPipelineStore = exports.isConnectorKind = exports.CONNECTOR_KINDS = exports.CATALOG_PIPELINE_STORE = exports.CatalogRegistry = exports.MikroOrmCatalogRegistry = exports.CATALOG_OVERLAY_STORE = exports.InMemoryCatalogOverlayStore = exports.FileCatalogOverlayStore = exports.CATALOG_OPTIONS = exports.isQueryStore = exports.assertReadOnlyShape = exports.CatalogModule = exports.emitCatalog = exports.curationActor = exports.channelNameFor = exports.catalogEventPhase = exports.UNATTRIBUTED_PRINCIPAL_ID = exports.CATALOG_LIB = exports.CATALOG_EVENTS = exports.CATALOG_EVENT_PHASE_FALLBACK = exports.CATALOG_EVENT_PHASE = exports.CatalogType = exports.CatalogProperty = void 0;
+exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.MikroOrmReadStore = exports.supportsCarryForward = exports.isWriteStore = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = exports.CATALOG_RESERVED_COLUMNS = exports.assertNoColumnCollisions = exports.StaticKeyPrincipalResolver = exports.readableObjectPage = exports.mayWrite = exports.mayRead = exports.maySeeClassification = exports.PRINCIPAL_ACTOR_SEPARATOR = exports.parsePrincipalId = exports.hasScope = exports.expandScopes = exports.delegatePrincipal = exports.composePrincipalId = exports.CATALOG_PRINCIPAL_RESOLVER = exports.traceOutcomeFilter = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.visibleToPrincipal = void 0;
 var catalog_decorators_1 = require("./catalog.decorators");
 Object.defineProperty(exports, "CatalogProperty", { enumerable: true, get: function () { return catalog_decorators_1.CatalogProperty; } });
 Object.defineProperty(exports, "CatalogType", { enumerable: true, get: function () { return catalog_decorators_1.CatalogType; } });
@@ -24,8 +24,10 @@ Object.defineProperty(exports, "CATALOG_EVENT_PHASE", { enumerable: true, get: f
 Object.defineProperty(exports, "CATALOG_EVENT_PHASE_FALLBACK", { enumerable: true, get: function () { return catalog_events_1.CATALOG_EVENT_PHASE_FALLBACK; } });
 Object.defineProperty(exports, "CATALOG_EVENTS", { enumerable: true, get: function () { return catalog_events_1.CATALOG_EVENTS; } });
 Object.defineProperty(exports, "CATALOG_LIB", { enumerable: true, get: function () { return catalog_events_1.CATALOG_LIB; } });
+Object.defineProperty(exports, "UNATTRIBUTED_PRINCIPAL_ID", { enumerable: true, get: function () { return catalog_events_1.UNATTRIBUTED_PRINCIPAL_ID; } });
 Object.defineProperty(exports, "catalogEventPhase", { enumerable: true, get: function () { return catalog_events_1.catalogEventPhase; } });
 Object.defineProperty(exports, "channelNameFor", { enumerable: true, get: function () { return catalog_events_1.channelNameFor; } });
+Object.defineProperty(exports, "curationActor", { enumerable: true, get: function () { return catalog_events_1.curationActor; } });
 Object.defineProperty(exports, "emitCatalog", { enumerable: true, get: function () { return catalog_events_1.emitCatalog; } });
 var catalog_module_1 = require("./catalog.module");
 Object.defineProperty(exports, "CatalogModule", { enumerable: true, get: function () { return catalog_module_1.CatalogModule; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-catalog",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "A metadata registry for NestJS: object types, properties and relations, derived from your ORM and enriched with decorators.",
   "license": "MIT",
   "author": "Davide Carvalho",