@dudousxd/nestjs-catalog 0.8.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

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

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

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

package/dist/catalog.overlay-store.js

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

package/dist/catalog.pipeline.d.ts

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

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

@@ -59,8 +59,39 @@ 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>;
-    abstract resetOverlay(): Promise<void>;
+    /**
+     * 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.
+     *
+     * **An implementation that really discards must emit `overlay.reset`**, and
+     * the reason is an asymmetry this class would otherwise have: the two patches
+     * above are audited one field at a time, so a trail could say who renamed one
+     * column and not who reverted every name in the catalog — while both need only
+     * `catalog:curate`. The summary has to be built before the write; nothing
+     * versions an overlay, so afterwards there is nothing left to read.
+     *
+     * **Refusing is an implementation too, and refusing emits nothing.** A
+     * registry whose curated values have no derived layer underneath them has
+     * nothing to fall back to, so a reset there is destruction rather than a
+     * revert, and the throw is the whole answer — no act, no record of one.
+     * `StoredCatalogRegistry` is that case.
+     *
+     * Which of those a deployment runs is why the event is worth more than the
+     * call it accompanies: a registry that quietly resets without emitting looks
+     * exactly like one that never ran a reset at all.
+     *
+     * @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(resetBy: string): Promise<void>;
 }

package/dist/catalog.registry.d.ts

@@ -32,10 +32,27 @@ 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>;
-    resetOverlay(): Promise<void>;
+    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.
+     *
+     * The summary is taken before the overlay is cleared because it is the only
+     * record there will ever be: nothing versions an overlay, so the discarded
+     * values are gone the instant the store is written. See `overlay.reset` in
+     * `catalog.events.ts` for why the payload is a summary and not a copy.
+     *
+     * Emitted after the write, like the two patches above, so the trail says what
+     * happened rather than what was about to.
+     *
+     * 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(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,12 +222,32 @@ 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);
     }
-    async resetOverlay() {
+    /**
+     * Drop every tier-0 edit, and leave a record that it happened.
+     *
+     * The summary is taken before the overlay is cleared because it is the only
+     * record there will ever be: nothing versions an overlay, so the discarded
+     * values are gone the instant the store is written. See `overlay.reset` in
+     * `catalog.events.ts` for why the payload is a summary and not a copy.
+     *
+     * Emitted after the write, like the two patches above, so the trail says what
+     * happened rather than what was about to.
+     *
+     * 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(resetBy) {
+        const discarded = summariseOverlay(this.overlay);
         this.overlay = { types: {} };
         await this.persist();
+        (0, catalog_events_1.emitCatalog)('overlay.reset', { ...discarded, principalId: (0, catalog_events_1.curationActor)(resetBy) });
     }
     async persist() {
         await this.overlayStore.save(this.overlay);
@@ -368,6 +392,46 @@ exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegis
     __param(2, (0, common_1.Inject)(catalog_overlay_store_token_1.CATALOG_OVERLAY_STORE)),
     __metadata("design:paramtypes", [core_1.MikroORM, Object, Object])
 ], MikroOrmCatalogRegistry);
+/**
+ * What a reset is about to destroy, in the shape the trail keeps it.
+ *
+ * Here rather than in `catalog.events.ts` because it reads a `CatalogOverlay`,
+ * and this is the only registry that has one — the payload type is the contract,
+ * this is one producer of it. Pure and taking the overlay as an argument so the
+ * 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
+ * the reset undid.
+ */
+function summariseOverlay(overlay) {
+    const typeNames = Object.keys(overlay.types);
+    const classifications = [];
+    let properties = 0;
+    for (const typeName of typeNames) {
+        const patched = overlay.types[typeName]?.properties ?? {};
+        for (const [property, patch] of Object.entries(patched)) {
+            properties += 1;
+            const { classification } = patch;
+            // Only a classification that was actually set. An entry that merely
+            // renamed the column carries the key as `undefined`, and listing it would
+            // report a classification lost that nobody had applied.
+            if (classification !== undefined) {
+                classifications.push({ typeName, property, classification });
+            }
+        }
+    }
+    return { typeNames, properties, classifications };
+}
 /**
  * How one field is presented, resolved across the tiers.
  *

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/dist/transform-runner.js

@@ -17,6 +17,57 @@ const node_path_1 = require("node:path");
 const common_1 = require("@nestjs/common");
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+/**
+ * How much of what a transform logged is carried back, on both axes.
+ *
+ * Both, because either one alone leaves the capture unbounded in the dimension
+ * it does not cover, and this capture is *user code writing whatever it likes*.
+ * A transform that logs one line per record — the most natural debugging move
+ * there is — puts a copy of the source's data into `logs`, and `logs` is the one
+ * thing that crosses a durable step boundary and lands in the run record. So the
+ * ceiling is fixed here, in the child, before any of it is serialised: the
+ * alternative is a `finishRun` write whose size is a property of somebody's
+ * data.
+ *
+ * The same two numbers for JavaScript and for Python, applied by the two
+ * harnesses below in the same order. A transform's log behaviour changing
+ * because of the language it happens to be written in is a difference nobody can
+ * predict from reading either one.
+ *
+ * Deliberately far above what anything downstream keeps — the connector runner
+ * takes fifty lines, the workflow runner twenty per node at four hundred
+ * characters — because this is the *safety* bound and those are the *display*
+ * bounds. A harness that truncated at the display limit would decide, in the
+ * child, what a future consumer is allowed to see.
+ *
+ * What is dropped is said out loud, in a final line, rather than dropped
+ * quietly. Silence about a missing log is the exact failure this whole capture
+ * exists to remove; reproducing it at line 501 would only move it.
+ */
+const MAX_LOG_LINES = 500;
+const MAX_LOG_LINE_CHARS = 2_000;
+/**
+ * How much of what a *failing* transform logged is folded into the error.
+ *
+ * A failure throws, and a throw carries a message and nothing else — so the
+ * `logs` of a run that raised never reach the caller at all, and every consumer
+ * records the traceback with none of the output that led to it. Capturing
+ * `print` and then discarding it at the exact moment it is most wanted would be
+ * a fix that stops one step short of the case it was written for.
+ *
+ * The **last** lines, not the first, which is the opposite of what the display
+ * caps downstream do — and deliberately. Those are trimming a successful run's
+ * narrative, where the beginning is the story; this is the approach to a
+ * traceback, where the last thing printed is the one that says where the code
+ * got to.
+ *
+ * Small on both axes because this lands in an error message, and an error
+ * message ends up in a run row, a log line and a console toast. The full set is
+ * still on the result whenever the transform returned at all; this is the
+ * consolation for the path where there is no result.
+ */
+const FAILURE_LOG_LINES = 10;
+const FAILURE_LOG_CHARS = 200;
 /** Packages worth telling the author about, if the environment has them. */
 const REPORTED_PACKAGES = ['pandas', 'numpy', 'pyarrow', 'requests'];
 /**
@@ -111,14 +162,15 @@ let SubprocessTransformRunner = SubprocessTransformRunner_1 = class SubprocessTr
         catch {
             throw new Error(`The transform did not return anything readable. stderr: ${stderr.slice(0, 500)}`);
         }
+        const logs = Array.isArray(parsed.logs) ? parsed.logs.map(String) : [];
         if (parsed.error)
-            throw new Error(parsed.error);
+            throw new Error(withFinalLogs(parsed.error, logs));
         if (!Array.isArray(parsed.rows)) {
             throw new Error('The transform must return an array of rows. Returning anything else would leave the load ambiguous.');
         }
         return {
             rows: parsed.rows.filter((row) => typeof row === 'object' && row !== null && !Array.isArray(row)),
-            logs: Array.isArray(parsed.logs) ? parsed.logs.map(String) : [],
+            logs,
             elapsedMs: Date.now() - started,
         };
     }
@@ -204,18 +256,68 @@ exports.SubprocessTransformRunner = SubprocessTransformRunner = SubprocessTransf
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [Object])
 ], SubprocessTransformRunner);
+/**
+ * The traceback, plus the tail of what the code printed on its way to it.
+ *
+ * Named in the message rather than appended bare, and counted rather than
+ * merely truncated: "the last 10 of 57 lines" tells a reader there is more to
+ * find on the run's own log, where a silent tail would let them believe they
+ * were looking at everything the transform said.
+ */
+function withFinalLogs(error, logs) {
+    if (logs.length === 0)
+        return error;
+    const tail = logs
+        .slice(-FAILURE_LOG_LINES)
+        .map((line) => line.length > FAILURE_LOG_CHARS ? `${line.slice(0, FAILURE_LOG_CHARS)}…` : line);
+    const heading = logs.length > tail.length
+        ? `The last ${tail.length} of ${logs.length} lines it logged first:`
+        : `${tail.length === 1 ? 'The line' : `The ${tail.length} lines`} it logged first:`;
+    return `${error}\n${heading}\n${tail.map((line) => `  ${line}`).join('\n')}`;
+}
 /**
  * The JavaScript and TypeScript harness.
  *
  * `console.log` is captured rather than left on stdout so user code cannot
  * corrupt the single JSON line this prints — a transform that logs a `{` would
  * otherwise break its own result parsing, which is a maddening thing to debug.
+ *
+ * Every console channel that reaches a terminal is overridden, not just the four
+ * that were here first. `console.debug` writes to stdout exactly as `console.log`
+ * does, so leaving it alone left one spelling of "log something" that silently
+ * corrupted the result line; `console.trace` writes to stderr, so leaving it
+ * alone left one spelling that silently went nowhere. Both are the same mistake
+ * the Python harness made with `print`, and there is no reading of "anything the
+ * code logged" under which they are not it.
+ *
+ * The channels share one array and keep call order, which is the only ordering
+ * that answers the question logs are read for — what happened, and in what
+ * sequence. Nothing marks which channel a line came from: a reader looking at a
+ * failed run wants the sequence, and splitting it into two lists would make the
+ * interleaving unrecoverable to buy a label the line's own text usually carries.
+ *
+ * Bounded by {@link MAX_LOG_LINES} and {@link MAX_LOG_LINE_CHARS}, applied here
+ * rather than after the fact, so a transform that logs a copy of its input never
+ * gets as far as being serialised.
  */
 function javascriptHarness(code) {
     return `
 const logs = [];
-const write = (...args) => logs.push(args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" "));
+let dropped = 0;
+const keep = (line) => {
+  if (logs.length >= ${MAX_LOG_LINES}) { dropped += 1; return; }
+  logs.push(
+    line.length > ${MAX_LOG_LINE_CHARS}
+      ? line.slice(0, ${MAX_LOG_LINE_CHARS}) + "… (" + (line.length - ${MAX_LOG_LINE_CHARS}) + " more characters)"
+      : line,
+  );
+};
+const write = (...args) => keep(args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" "));
 console.log = write; console.info = write; console.warn = write; console.error = write;
+console.debug = write; console.trace = write;
+const captured = () => dropped === 0
+  ? logs
+  : logs.concat(["… " + dropped + " more line(s) were logged and dropped: a transform keeps its first ${MAX_LOG_LINES}."]);
 
 let input = "";
 process.stdin.setEncoding("utf8");
@@ -225,11 +327,11 @@ try {
   const records = JSON.parse(input || "[]");
   const transform = async (records) => { ${code} };
   const rows = await transform(records);
-  process.stdout.write(JSON.stringify({ rows: rows ?? [], logs }));
+  process.stdout.write(JSON.stringify({ rows: rows ?? [], logs: captured() }));
 } catch (error) {
   process.stdout.write(JSON.stringify({
     error: error instanceof Error ? \`\${error.name}: \${error.message}\` : String(error),
-    logs,
+    logs: captured(),
   }));
 }
 `;
@@ -241,6 +343,44 @@ try {
  * that reaches for pandas will naturally end with one — making it write
  * `.to_dict("records")` would be a papercut on the only path pandas is worth
  * importing for.
+ *
+ * **`print` is redirected, for the same reason `console.log` is.** It used to go
+ * straight through to the child's real stdout, where the last-line result parse
+ * discarded it — so the single most obvious thing a person writes while working
+ * out what their transform is doing produced an empty log panel and no
+ * explanation. That is not a missing nicety: it costs the author their trust in
+ * the runner before they have written anything real, and the conclusion it
+ * invites ("my code never ran") is the wrong one. `log()` still exists, because
+ * transforms in the wild call it and a `NameError` is a worse answer than a
+ * redundant helper, but it is now literally `print` — one buffer, one ordering,
+ * and nothing that only works if you already knew about it.
+ *
+ * **stderr is captured too**, into the same list and in call order. `warnings`,
+ * a `logging` handler at its default configuration, and a traceback the code
+ * printed itself all land there, and those are precisely the lines somebody is
+ * looking for when a transform misbehaves. It is not marked as stderr, matching
+ * the JavaScript harness, which does not distinguish `console.error` either: the
+ * sequence is what a reader is reconstructing, and two lists would make the
+ * interleaving unrecoverable.
+ *
+ * What was written **before** an exception survives it. The redirect is a
+ * context manager around the call rather than a swap held for the whole script,
+ * so it unwinds on the way out of a traceback with the buffer intact, and the
+ * error branch reports the same lines the success branch would have. A
+ * transform that printed three things and then divided by zero is the case logs
+ * matter most for, and it is the case a naive swap loses.
+ *
+ * Bounded by {@link MAX_LOG_LINES} and {@link MAX_LOG_LINE_CHARS}, the same two
+ * numbers the JavaScript harness applies. Note that this bounds the *sink*, not
+ * only the result: an unterminated write longer than a line's ceiling is flushed
+ * as its own line rather than accumulated, so a transform writing without
+ * newlines cannot grow the child's memory either.
+ *
+ * The limit worth stating: this redirects Python-level writes to `sys.stdout`
+ * and `sys.stderr`. Output from a C extension or a subprocess that writes to the
+ * file descriptors underneath goes to the real streams, exactly as it does past
+ * an overridden `console` in Node. Redirecting the descriptors themselves would
+ * take the result channel with it.
  */
 function pythonHarness(code) {
     const indented = code
@@ -248,11 +388,68 @@ function pythonHarness(code) {
         .map((line) => `    ${line}`)
         .join('\n');
     return `
-import sys, json
+import sys, json, contextlib
 
 logs = []
+# A one-element list rather than a module global reassigned inside the helper,
+# so the counter needs no \`global\` statement in generated code.
+dropped = [0]
+
+def keep(line):
+    if len(logs) >= ${MAX_LOG_LINES}:
+        dropped[0] += 1
+        return
+    if len(line) > ${MAX_LOG_LINE_CHARS}:
+        line = "{}… ({} more characters)".format(
+            line[:${MAX_LOG_LINE_CHARS}], len(line) - ${MAX_LOG_LINE_CHARS}
+        )
+    logs.append(line)
+
+class Sink:
+    """Stands in for stdout and stderr while the transform runs.
+
+    Line-buffered by hand because \`print("a", "b")\` arrives as four separate
+    writes — the parts, the separators and the terminator — and appending each
+    one as its own entry would shred every multi-argument call.
+    """
+
+    def __init__(self):
+        self.partial = ""
+
+    def write(self, text):
+        if not isinstance(text, str):
+            text = str(text)
+        self.partial += text
+        while "\\n" in self.partial:
+            line, self.partial = self.partial.split("\\n", 1)
+            keep(line)
+        # A write with no newline in it is still bounded: past a line's ceiling
+        # there is nothing more to keep, so it is emitted rather than held.
+        if len(self.partial) > ${MAX_LOG_LINE_CHARS}:
+            keep(self.partial)
+            self.partial = ""
+        return len(text)
+
+    def writelines(self, lines):
+        for line in lines:
+            self.write(line)
+
+    def flush(self):
+        pass
+
+    def isatty(self):
+        return False
+
+    def drain(self):
+        """Whatever was written without a trailing newline is still output."""
+        if self.partial:
+            keep(self.partial)
+            self.partial = ""
+
+sink = Sink()
+
 def log(*args):
-    logs.append(" ".join(str(a) for a in args))
+    print(*args)
 
 def transform(records):
 ${indented || '    return records'}
@@ -266,15 +463,31 @@ def to_rows(result):
         return result.to_dict("records")
     return result
 
+def captured():
+    sink.drain()
+    if dropped[0] == 0:
+        return logs
+    return logs + [
+        "… {} more line(s) were logged and dropped: a transform keeps its first {}.".format(
+            dropped[0], ${MAX_LOG_LINES}
+        )
+    ]
+
 try:
     raw = sys.stdin.read()
     records = json.loads(raw) if raw.strip() else []
-    rows = to_rows(transform(records))
-    sys.stdout.write(json.dumps(rows and {"rows": rows, "logs": logs} or {"rows": [], "logs": logs}, default=str))
+    # \`to_rows\` is inside the redirect as well: a lazily-evaluated return value
+    # does its printing here, not before.
+    with contextlib.redirect_stdout(sink), contextlib.redirect_stderr(sink):
+        rows = to_rows(transform(records))
+    # Back on the real stdout by now — the context manager restores on the way
+    # out, including out of an exception — so this is the only thing on it.
+    out = captured()
+    sys.stdout.write(json.dumps(rows and {"rows": rows, "logs": out} or {"rows": [], "logs": out}, default=str))
 except Exception as error:
     sys.stdout.write(json.dumps({
         "error": "{}: {}".format(type(error).__name__, error),
-        "logs": logs,
+        "logs": captured(),
     }))
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-catalog",
-  "version": "0.8.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",