@dudousxd/nestjs-catalog 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Carvalho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,123 @@
+# @dudousxd/nestjs-catalog
+
+A metadata registry for NestJS. It reads your ORM and gives you back your data
+model as data: object types, their properties, their relations — queryable over
+HTTP, and labelled by humans rather than by whoever named the class.
+
+```bash
+pnpm add @dudousxd/nestjs-catalog
+```
+
+## Why
+
+Most applications describe their model three or four times: once in the entity,
+once in a filter definition, once in a table component, once in whatever the
+admin screen is. Each copy drifts.
+
+This library takes the position that **structure should be derived and semantics
+should be declared.** Column names, SQL types, nullability and foreign keys are
+read off the ORM, because the database already knows them. What the database
+cannot know — what a thing is called, what it means, what unit it is in, who may
+see it — is declared once and served to everything downstream.
+
+## Mount it
+
+```ts
+import { CatalogModule } from "@dudousxd/nestjs-catalog";
+
+@Module({
+  imports: [
+    CatalogModule.forRoot({
+      path: "catalog",
+      // No guard ships by default. An endpoint that enumerates every table in
+      // your database should never be open because a library decided so.
+      imports: [AuthModule],
+      guards: [RolesGuard],
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`imports` is not decoration: Nest builds a guard from the injector of the module
+that *declares* the controller, and this library generates its own. Whatever
+your guards inject has to be resolvable from there.
+
+## Declare what the database cannot know
+
+```ts
+@CatalogType({
+  displayName: "Vehicle",
+  group: "Fleet",
+  icon: "🚚",
+  description: "One registered vehicle. Work orders and funding hang off it.",
+})
+@Entity()
+export class Mvr {
+  @CatalogProperty({ displayName: "Risk Score", unit: "0–100" })
+  @Property({ fieldName: "Risk Score" })
+  riskScore?: number;
+}
+```
+
+Entities with no decorators still appear — with a name derived from the class,
+which is exactly the point: the console shows you which types nobody has named
+yet.
+
+## The HTTP surface
+
+| Method | Path | What it does |
+|---|---|---|
+| `GET` | `/catalog` | The whole model, as data |
+| `GET` | `/catalog/graph` | Nodes and edges, for drawing it |
+| `GET` | `/catalog/types/:name` | One type |
+| `PATCH` | `/catalog/types/:name` | Rename, regroup, re-describe |
+| `PATCH` | `/catalog/types/:name/properties/:property` | Label, unit, description, visibility |
+| `POST` | `/catalog/reset` | Drop every runtime edit |
+| `GET` | `/catalog/objects/:name` | Read rows of any catalogued type |
+
+Everything a `PATCH` can change is presentation-only. **No route in this library
+issues DDL, and the catalog never writes to your tables.** Runtime edits go to an
+overlay store (a JSON file by default; bring your own via `overlayStore`).
+
+`GET /catalog/objects/:name` validates the type name, the sort column and the
+searched columns against the catalog before anything reaches SQL, selects only
+the columns the catalog says are visible, and caps the page size.
+
+## Build your own endpoints, or use ours
+
+The built-in controller is a convenience, not the interface. Pass
+`controller: false` and inject `CatalogService` — by class, there is no token to
+import — to publish whatever HTTP surface your app already uses:
+
+```ts
+@Controller("data-model")
+export class MyController {
+  constructor(private readonly catalog: CatalogService) {}
+
+  @Get()        model()               { return this.catalog.getSnapshot(); }
+  @Get("graph") graph()               { return this.catalog.getGraph(); }
+  @Get(":type") rows(@Param("type") t: string, @Query() q) {
+    return this.catalog.readObjects(t, q);
+  }
+}
+```
+
+Everything the built-in controller does is on that one service — the model, the
+graph, presentation edits, reads, and the snapshot list. The registry and the
+store stay injectable for anything more unusual, but an ordinary endpoint should
+not need them.
+
+## Build your own UI, or use ours
+
+The endpoints are the product. Import `@dudousxd/nestjs-catalog/client` for the
+response types and route builders — no NestJS, no ORM, browser-safe — and write
+whatever screens you want.
+
+If you would rather not, [`@dudousxd/nestjs-catalog-react`](../nestjs-catalog-react)
+ships a model manager and a generic object explorer that you drop into your own
+app shell.
+
+## License
+
+MIT

package/dist/catalog.controller.d.ts

@@ -0,0 +1,8 @@
+import { type Type } from '@nestjs/common';
+/**
+ * Built as a factory rather than a plain class because the route prefix and the
+ * guards both come from `forRoot`. A library that hardcodes either one forces
+ * every host app to accept its idea of auth, which for an endpoint that
+ * enumerates every table in the database is not a reasonable default.
+ */
+export declare function createCatalogController(path: string, guards: Type<unknown>[], decorators?: ClassDecorator[]): Type<unknown>;

package/dist/catalog.controller.js

@@ -0,0 +1,482 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCatalogController = createCatalogController;
+const common_1 = require("@nestjs/common");
+const catalog_query_cache_1 = require("./catalog.query-cache");
+const catalog_registry_base_1 = require("./catalog.registry.base");
+const catalog_service_1 = require("./catalog.service");
+const catalog_workspace_1 = require("./catalog.workspace");
+/**
+ * Built as a factory rather than a plain class because the route prefix and the
+ * guards both come from `forRoot`. A library that hardcodes either one forces
+ * every host app to accept its idea of auth, which for an endpoint that
+ * enumerates every table in the database is not a reasonable default.
+ */
+function createCatalogController(path, guards, decorators = []) {
+    let CatalogController = class CatalogController {
+        registry;
+        service;
+        traces;
+        constructor(registry, service, traces) {
+            this.registry = registry;
+            this.service = service;
+            this.traces = traces;
+        }
+        requireTraces() {
+            if (!this.traces) {
+                throw new common_1.BadRequestException('This catalog has no trace store, so the audit trail can be listed but not grouped into traces.');
+            }
+            return this.traces;
+        }
+        /** The whole ontology, as data. */
+        snapshot() {
+            return this.registry.getSnapshot();
+        }
+        /** Nodes and edges, for drawing it. */
+        graph() {
+            return this.registry.getGraph();
+        }
+        type(name) {
+            const type = this.registry.getType(name);
+            if (!type)
+                throw new common_1.NotFoundException(`Unknown object type: ${name}`);
+            return type;
+        }
+        /**
+         * Tier 0. Renames a type, regroups it, changes its icon. No migration, no
+         * deploy, no engineer.
+         */
+        async patchType(name, body) {
+            const updated = await this.registry.patchType(name, body);
+            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);
+            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();
+            return this.registry.getSnapshot();
+        }
+        /** One generic read endpoint for every type in the catalog. */
+        objects(name, page, size, search, sort, dir, snapshot) {
+            return this.service.readObjects(name, {
+                page: page ? Number(page) : undefined,
+                size: size ? Number(size) : undefined,
+                search,
+                sort,
+                dir: dir === 'desc' ? 'desc' : 'asc',
+                snapshot,
+            });
+        }
+        /** What an ad-hoc query may select from, and whether it can run at all. */
+        queryRelations() {
+            return this.service.queryRelations();
+        }
+        /** Run one read-only statement. */
+        runQuery(body) {
+            return this.service.runQuery(body ?? { sql: '' });
+        }
+        /** Everything a saved query or dashboard needs to know is here. */
+        workspaceCapabilities() {
+            return {
+                workspace: this.service.workspaceAvailable(),
+                ...this.service.capabilities(),
+            };
+        }
+        savedQueries() {
+            return this.service.listSavedQueries();
+        }
+        saveSavedQuery(body) {
+            return this.service.saveQuery(body, body?.createdBy ?? 'console');
+        }
+        savedQuery(id) {
+            return this.service.getSavedQuery(id);
+        }
+        patchSavedQuery(id, body) {
+            return this.service.updateSavedQuery(id, body);
+        }
+        removeSavedQuery(id) {
+            return this.service.deleteSavedQuery(id).then((deleted) => ({ deleted }));
+        }
+        /** Run a saved query, honouring the cache TTL it was saved with. */
+        runSavedQuery(id, body) {
+            return this.service.runSavedQuery(id, body?.maxRows);
+        }
+        /**
+         * The same result as CSV.
+         *
+         * A GET, not a POST, so it can be a plain link — a download that only works
+         * from JavaScript cannot be pasted into a mail or a scheduled job.
+         */
+        async exportSavedQuery(id, response) {
+            const { savedQuery, result } = await this.service.runSavedQuery(id);
+            const filename = `${savedQuery.name.replace(/[^A-Za-z0-9_-]+/g, '-')}.csv`;
+            response.setHeader('content-type', 'text/csv; charset=utf-8');
+            response.setHeader('content-disposition', `attachment; filename="${filename}"`);
+            return (0, catalog_query_cache_1.toCsv)(result);
+        }
+        dashboards() {
+            return this.service.listDashboards();
+        }
+        createDashboard(body) {
+            return this.service.saveDashboard(body, body?.createdBy ?? 'console');
+        }
+        dashboard(id) {
+            return this.service.getDashboard(id);
+        }
+        patchDashboard(id, body) {
+            return this.service.updateDashboard(id, body);
+        }
+        removeDashboard(id) {
+            return this.service.deleteDashboard(id).then((deleted) => ({ deleted }));
+        }
+        /**
+         * What this caller may embed.
+         *
+         * A discovery endpoint so a consuming frontend can list what it is allowed
+         * to render rather than being told the ids out of band.
+         */
+        embeddable() {
+            return this.service.listEmbeddable();
+        }
+        /** A whole dashboard, every chart resolved and ready to draw. */
+        embedDashboard(id) {
+            return this.service.embedDashboard(id);
+        }
+        /** One chart, for a consumer that wants to place it itself. */
+        embedChart(id) {
+            return this.service.embedChart(id);
+        }
+        /** The audit trail: what happened, to what, by whom. */
+        events(event, typeName, principalId, since, limit) {
+            return this.service.listEvents({
+                event,
+                typeName,
+                principalId,
+                since,
+                limit: limit ? Number(limit) : undefined,
+            });
+        }
+        /**
+         * The same trail, grouped into causal stories.
+         *
+         * Declared after `events` and before anything with a parameter in that
+         * position, so `traces` is matched as the literal it is. Nest resolves
+         * routes in declaration order, and a `:something` registered first would
+         * swallow this path and answer it with a lookup for an event named
+         * "traces" — a 404 nobody could explain.
+         *
+         * `event` and `outcome` pick *which traces* come back, never which spans:
+         * a trace returned with only its matching events would be a story with
+         * pages missing that still looked complete.
+         */
+        traceList(typeName, principalId, event, outcome, since, limit, offset) {
+            return this.requireTraces().listTraces({
+                typeName,
+                principalId,
+                event,
+                outcome: parseOutcomes(outcome),
+                since,
+                limit: limit ? Number(limit) : undefined,
+                offset: offset ? Number(offset) : undefined,
+            });
+        }
+        /** One story in full, by correlation id. */
+        async trace(id) {
+            const found = await this.requireTraces().getTrace(id);
+            if (!found) {
+                throw new common_1.NotFoundException(`No trace ${id} in the audit trail.`);
+            }
+            return found;
+        }
+        /** Every load of this type: when, by whom, how many rows. */
+        snapshots(name) {
+            return this.service.listSnapshots(name);
+        }
+    };
+    __decorate([
+        (0, common_1.Get)(),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "snapshot", null);
+    __decorate([
+        (0, common_1.Get)('graph'),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "graph", null);
+    __decorate([
+        (0, common_1.Get)('types/:name'),
+        __param(0, (0, common_1.Param)('name')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "type", null);
+    __decorate([
+        (0, common_1.Patch)('types/:name'),
+        __param(0, (0, common_1.Param)('name')),
+        __param(1, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, Object]),
+        __metadata("design:returntype", Promise)
+    ], CatalogController.prototype, "patchType", null);
+    __decorate([
+        (0, common_1.Patch)('types/:name/properties/:property'),
+        __param(0, (0, common_1.Param)('name')),
+        __param(1, (0, common_1.Param)('property')),
+        __param(2, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, String, Object]),
+        __metadata("design:returntype", Promise)
+    ], CatalogController.prototype, "patchProperty", null);
+    __decorate([
+        (0, common_1.Post)('reset'),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", Promise)
+    ], CatalogController.prototype, "reset", null);
+    __decorate([
+        (0, common_1.Get)('objects/:name'),
+        __param(0, (0, common_1.Param)('name')),
+        __param(1, (0, common_1.Query)('page')),
+        __param(2, (0, common_1.Query)('size')),
+        __param(3, (0, common_1.Query)('search')),
+        __param(4, (0, common_1.Query)('sort')),
+        __param(5, (0, common_1.Query)('dir')),
+        __param(6, (0, common_1.Query)('snapshot')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, String, String, String, String, String, String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "objects", null);
+    __decorate([
+        (0, common_1.Get)('query/relations'),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "queryRelations", null);
+    __decorate([
+        (0, common_1.Post)('query'),
+        __param(0, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "runQuery", null);
+    __decorate([
+        (0, common_1.Get)('workspace/capabilities'),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "workspaceCapabilities", null);
+    __decorate([
+        (0, common_1.Get)('saved-queries'),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "savedQueries", null);
+    __decorate([
+        (0, common_1.Post)('saved-queries'),
+        __param(0, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "saveSavedQuery", null);
+    __decorate([
+        (0, common_1.Get)('saved-queries/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "savedQuery", null);
+    __decorate([
+        (0, common_1.Patch)('saved-queries/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __param(1, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "patchSavedQuery", null);
+    __decorate([
+        (0, common_1.Delete)('saved-queries/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "removeSavedQuery", null);
+    __decorate([
+        (0, common_1.Post)('saved-queries/:id/run'),
+        __param(0, (0, common_1.Param)('id')),
+        __param(1, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "runSavedQuery", null);
+    __decorate([
+        (0, common_1.Get)('saved-queries/:id/export.csv'),
+        __param(0, (0, common_1.Param)('id')),
+        __param(1, (0, common_1.Res)({ passthrough: true })),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, Object]),
+        __metadata("design:returntype", Promise)
+    ], CatalogController.prototype, "exportSavedQuery", null);
+    __decorate([
+        (0, common_1.Get)('dashboards'),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "dashboards", null);
+    __decorate([
+        (0, common_1.Post)('dashboards'),
+        __param(0, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "createDashboard", null);
+    __decorate([
+        (0, common_1.Get)('dashboards/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "dashboard", null);
+    __decorate([
+        (0, common_1.Patch)('dashboards/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __param(1, (0, common_1.Body)()),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, Object]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "patchDashboard", null);
+    __decorate([
+        (0, common_1.Delete)('dashboards/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "removeDashboard", null);
+    __decorate([
+        (0, common_1.Get)('embed'),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", []),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "embeddable", null);
+    __decorate([
+        (0, common_1.Get)('embed/dashboards/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "embedDashboard", null);
+    __decorate([
+        (0, common_1.Get)('embed/charts/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "embedChart", null);
+    __decorate([
+        (0, common_1.Get)('events'),
+        __param(0, (0, common_1.Query)('event')),
+        __param(1, (0, common_1.Query)('type')),
+        __param(2, (0, common_1.Query)('principal')),
+        __param(3, (0, common_1.Query)('since')),
+        __param(4, (0, common_1.Query)('limit')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, String, String, String, String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "events", null);
+    __decorate([
+        (0, common_1.Get)('events/traces'),
+        __param(0, (0, common_1.Query)('type')),
+        __param(1, (0, common_1.Query)('principal')),
+        __param(2, (0, common_1.Query)('event')),
+        __param(3, (0, common_1.Query)('outcome')),
+        __param(4, (0, common_1.Query)('since')),
+        __param(5, (0, common_1.Query)('limit')),
+        __param(6, (0, common_1.Query)('offset')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String, String, String, Object, String, String, String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "traceList", null);
+    __decorate([
+        (0, common_1.Get)('events/traces/:id'),
+        __param(0, (0, common_1.Param)('id')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", Promise)
+    ], CatalogController.prototype, "trace", null);
+    __decorate([
+        (0, common_1.Get)('objects/:name/snapshots'),
+        __param(0, (0, common_1.Param)('name')),
+        __metadata("design:type", Function),
+        __metadata("design:paramtypes", [String]),
+        __metadata("design:returntype", void 0)
+    ], CatalogController.prototype, "snapshots", null);
+    CatalogController = __decorate([
+        (0, common_1.Controller)(path),
+        __param(2, (0, common_1.Optional)()),
+        __param(2, (0, common_1.Inject)(catalog_workspace_1.CATALOG_TRACE_STORE)),
+        __metadata("design:paramtypes", [catalog_registry_base_1.CatalogRegistry,
+            catalog_service_1.CatalogService, Object])
+    ], CatalogController);
+    if (guards.length > 0) {
+        (0, common_1.UseGuards)(...guards)(CatalogController);
+    }
+    for (const decorate of decorators) {
+        decorate(CatalogController);
+    }
+    return CatalogController;
+}
+/**
+ * `?outcome=failed`, `?outcome=failed,incomplete`, `?outcome=a&outcome=b`.
+ *
+ * Two behaviours here are load-bearing and neither is obvious.
+ *
+ * An unrecognised outcome is dropped rather than passed down as a filter that
+ * matches nothing, and if nothing recognisable is left the filter goes away
+ * entirely. Returning an empty list for a typo would read as "no traces
+ * failed", which is the most expensive wrong answer this endpoint could give.
+ *
+ * A single outcome comes back as a bare string rather than a one-element array.
+ * `TraceQuery.outcome` accepts both, but a trace store written against the
+ * earlier contract expects only the string and would compare its column to an
+ * array — matching nothing, and reporting it as a clean empty page. So the
+ * array form is only ever produced when the caller genuinely asked for more
+ * than one, which is also the only case where an older store could not have
+ * answered anyway.
+ */
+function parseOutcomes(raw) {
+    if (raw === undefined)
+        return undefined;
+    const candidates = (Array.isArray(raw) ? raw : [raw]).flatMap((value) => String(value).split(','));
+    const outcomes = [];
+    for (const candidate of candidates) {
+        const trimmed = candidate.trim();
+        if ((0, catalog_workspace_1.isCatalogTraceOutcome)(trimmed) && !outcomes.includes(trimmed)) {
+            outcomes.push(trimmed);
+        }
+    }
+    if (outcomes.length === 0)
+        return undefined;
+    return outcomes.length === 1 ? outcomes[0] : outcomes;
+}

package/dist/catalog.decorators.d.ts

@@ -0,0 +1,37 @@
+import 'reflect-metadata';
+export declare const CATALOG_TYPE_META: unique symbol;
+export declare const CATALOG_PROPERTY_META: unique symbol;
+export interface CatalogTypeOptions {
+    displayName?: string;
+    pluralDisplayName?: string;
+    description?: string;
+    icon?: string;
+    group?: string;
+    titleProperty?: string;
+}
+export interface CatalogPropertyOptions {
+    displayName?: string;
+    description?: string;
+    hidden?: boolean;
+    order?: number;
+    classification?: string;
+    unit?: string;
+}
+/**
+ * Declares the semantics the database cannot know: what this entity is called
+ * in the business, which section it belongs to, and what to show when it
+ * appears as a link somewhere else.
+ *
+ * Structure is never declared here — it is read off the ORM. An entity with no
+ * `@CatalogType` still appears in the catalog, just with a name derived from
+ * its class and no group.
+ */
+export declare function CatalogType(options?: CatalogTypeOptions): ClassDecorator;
+/**
+ * Enriches one property. Everything it sets is tier 0 — the overlay can
+ * override any of it at runtime without a migration, which is precisely why
+ * these live in metadata rather than in the column definition.
+ */
+export declare function CatalogProperty(options?: CatalogPropertyOptions): PropertyDecorator;
+export declare function readTypeOptions(target: unknown): CatalogTypeOptions;
+export declare function readPropertyOptions(target: unknown): Record<string, CatalogPropertyOptions>;