@dudousxd/nestjs-catalog 0.9.0 → 0.11.0

package/dist/catalog.controller.js

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

package/dist/catalog.events.d.ts

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

package/dist/catalog.events.js

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

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

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

package/dist/catalog.overlay-store.js

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

package/dist/catalog.pipeline.d.ts

@@ -442,13 +442,48 @@ export interface WorkflowGraph {
  * an audit. The limitation is real and worth stating plainly — an edited graph
  * cannot be reconstructed from an old run, only identified as different.
  */
+/**
+ * Whether this graph is still being drawn, or is something somebody declared
+ * finished.
+ *
+ * The distinction exists because validation used to be the gate on *saving*, and
+ * that made an unfinished graph unstorable: `saveWorkflow` refused anything
+ * `validateWorkflow` had an issue with, so a canvas with one node on it could
+ * not be written down at all and closing the tab lost it. Worse, it made the
+ * canvas lie about ordinary work — clicking "+ Sink" produces a node that is
+ * unreachable from any source and names no type, both true and both useless one
+ * second after the click, because a just-added node is unwired by construction.
+ *
+ * So the gate moved rather than loosened. Validation is now the gate on
+ * publishing, and the same `validateWorkflow` still decides — a draft is not a
+ * graph that skipped the rules, it is a graph nobody has claimed is finished
+ * yet. Everything that consumes a workflow asks for `ready`: a connector may
+ * only point at one, and a promotion may only carry one. What crosses an
+ * environment should be something a person declared done.
+ */
+export declare const WORKFLOW_STATUSES: readonly ["draft", "ready"];
+export type WorkflowStatus = (typeof WORKFLOW_STATUSES)[number];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+export declare function isWorkflowStatus(value: unknown): value is WorkflowStatus;
 export interface CatalogWorkflow {
     id: string;
     name: string;
     description?: string;
     nodes: WorkflowNode[];
     edges: WorkflowEdge[];
-    /** Bumped whenever the graph's behaviour changes. Never on a rename or a move. */
+    /** See {@link WORKFLOW_STATUSES}. A graph is `draft` until somebody publishes it. */
+    status: WorkflowStatus;
+    /**
+     * Bumped whenever the graph's behaviour changes. Never on a rename or a move.
+     *
+     * Bumped on a **draft** edit too, which looks like exactly the inflation this
+     * rule exists to prevent and is not. The counter's job is to make
+     * {@link ConnectorRun.workflowVersion} answer "which shape ran": freezing it
+     * while a graph is drafted would let a run recorded at v4 and a later run also
+     * at v4 mean two different graphs, which is the one thing that field must
+     * never do. Drafting therefore inflates a number nobody reads — cheap — rather
+     * than making a number somebody does read ambiguous.
+     */
     version: number;
     /** Fingerprint of the graph at this version. See {@link workflowGraphHash}. */
     graphHash: string;
@@ -660,7 +695,24 @@ export interface CatalogWorkflowStore {
     listWorkflows(): Promise<CatalogWorkflow[]>;
     getWorkflow(id: string): Promise<CatalogWorkflow | undefined>;
     /**
-     * Validates before it writes, and refuses naming the node.
+     * Writes. Validates only what it must.
+     *
+     * A **draft** is written without validating, which is the whole of the change
+     * and the reason {@link WORKFLOW_STATUSES} exists: a graph you have not
+     * finished has to be storable, or closing the tab loses it. A **ready**
+     * workflow is still validated on every save, because it is the one that runs.
+     *
+     * `status` is not an input. A save cannot promote a draft to ready — that is
+     * {@link publishWorkflow}, which exists so there is one place that validates
+     * and one place that can explain why it refused. A save of an already-ready
+     * workflow keeps it ready, and **refuses an edit that would make it invalid**
+     * rather than quietly demoting it to draft. Demotion was the other option and
+     * it is the one that loses a running pipeline silently: a connector may only
+     * point at a ready graph, so a save that dropped the status would disable a
+     * scheduled load with nothing said to anybody. Refusing puts the error in
+     * front of the person who is editing, at the moment they edit. To park a
+     * broken idea on a live graph, {@link unpublishWorkflow} it first and be told
+     * which connectors that stops.
      *
      * `version`, `graphHash` and `targetType` are not inputs: the first two are
      * derived from the graph and the third from the sink, and accepting them from
@@ -670,6 +722,34 @@ export interface CatalogWorkflowStore {
         id?: string;
         description?: string;
     }, createdBy: string): Promise<CatalogWorkflow>;
+    /**
+     * Declare a graph finished: validate it, and make it `ready`.
+     *
+     * A transition rather than a field on save, and the argument is that this is
+     * the only shape with somewhere to put the refusal. "Ready" is a claim that
+     * has to be checked, and a check that fails owes an explanation naming the
+     * nodes — `validateWorkflow` produces exactly that, and a boolean field on a
+     * save request has nowhere to return it that is not an error on an operation
+     * the caller thought was about something else. It also makes the audit
+     * question answerable: publishing is an act with an actor, and a field set in
+     * passing during an autosave is not.
+     *
+     * Idempotent on an already-ready graph, because the honest answer to "publish
+     * this thing that is published" is the graph, not an error.
+     */
+    publishWorkflow(id: string, publishedBy: string): Promise<CatalogWorkflow>;
+    /**
+     * Take a graph back to `draft`.
+     *
+     * **Refuses while any connector still runs it**, exactly as
+     * {@link deleteWorkflow} does and for the same reason: a connector may only
+     * point at a ready graph, so unpublishing one out from under a schedule breaks
+     * a load that was working, and the operator needs to know *which* connectors
+     * to point elsewhere first. Refusing here rather than cascading is deliberate —
+     * disabling somebody's connectors as a side effect of an edit to something
+     * else is precisely the silent action this status exists to prevent.
+     */
+    unpublishWorkflow(id: string, unpublishedBy: string): Promise<CatalogWorkflow>;
     /** Refuses while any connector still runs it. */
     deleteWorkflow(id: string): Promise<boolean>;
     /** Which connectors run it. Named, so a refusal can say. */

package/dist/catalog.pipeline.js

@@ -9,10 +9,11 @@
  * systems each believing they decide when a load runs.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
+exports.CATALOG_PIPELINE_STORE = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_STATUSES = exports.WORKFLOW_NODE_ID_PATTERN = exports.WORKFLOW_NODE_KINDS = exports.TRANSFORM_RUNNER = exports.TRANSFORM_LANGUAGES = exports.CONNECTOR_KINDS = void 0;
 exports.isConnectorKind = isConnectorKind;
 exports.isTransformLanguage = isTransformLanguage;
 exports.isWorkflowNodeKind = isWorkflowNodeKind;
+exports.isWorkflowStatus = isWorkflowStatus;
 exports.isWorkflowExecutionMode = isWorkflowExecutionMode;
 exports.validateWorkflow = validateWorkflow;
 exports.workflowRunOrder = workflowRunOrder;
@@ -136,6 +137,57 @@ function isWorkflowNodeKind(value) {
  * separator would let one node read another's rows.
  */
 exports.WORKFLOW_NODE_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+/**
+ * An authored graph of steps ending in one commit.
+ *
+ * Versioned the way {@link CatalogTransform} is, and for the same question: a
+ * load that produced surprising numbers is investigated afterwards, and "what
+ * ran" is the first thing asked. For a single-transform connector that means
+ * the code; for a workflow it means the code *and* the wiring, so both the
+ * graph version and the per-node transform versions are recorded on the run.
+ *
+ * Like a transform, only the latest shape is kept. Storing every past graph was
+ * the alternative and was rejected for consistency: transforms already answer
+ * "which code ran" with a number and no history, and a model where the graph is
+ * fully recoverable but the code inside it is not would give false confidence in
+ * an audit. The limitation is real and worth stating plainly — an edited graph
+ * cannot be reconstructed from an old run, only identified as different.
+ */
+/**
+ * Whether this graph is still being drawn, or is something somebody declared
+ * finished.
+ *
+ * The distinction exists because validation used to be the gate on *saving*, and
+ * that made an unfinished graph unstorable: `saveWorkflow` refused anything
+ * `validateWorkflow` had an issue with, so a canvas with one node on it could
+ * not be written down at all and closing the tab lost it. Worse, it made the
+ * canvas lie about ordinary work — clicking "+ Sink" produces a node that is
+ * unreachable from any source and names no type, both true and both useless one
+ * second after the click, because a just-added node is unwired by construction.
+ *
+ * So the gate moved rather than loosened. Validation is now the gate on
+ * publishing, and the same `validateWorkflow` still decides — a draft is not a
+ * graph that skipped the rules, it is a graph nobody has claimed is finished
+ * yet. Everything that consumes a workflow asks for `ready`: a connector may
+ * only point at one, and a promotion may only carry one. What crosses an
+ * environment should be something a person declared done.
+ */
+exports.WORKFLOW_STATUSES = [
+    /**
+     * Being drawn. Saves without validating, and cannot run, be scheduled, or be
+     * promoted. An incomplete node here is the normal state rather than an alarm.
+     */
+    'draft',
+    /**
+     * Declared finished, and validated at the moment it was declared. This is the
+     * only status a connector may point at and the only one a promotion carries.
+     */
+    'ready',
+];
+/** Same reason as {@link isConnectorKind}: one list, no second copy to drift. */
+function isWorkflowStatus(value) {
+    return exports.WORKFLOW_STATUSES.some((status) => status === value);
+}
 /**
  * How a workflow run is executed here.
  *
@@ -634,7 +686,13 @@ function isWorkflowEdge(value) {
 function supportsWorkflows(store) {
     return (typeof store.listWorkflows === 'function' &&
         typeof store.getWorkflow === 'function' &&
-        typeof store.saveWorkflow === 'function');
+        typeof store.saveWorkflow === 'function' &&
+        // Asked for by name like the rest, rather than assumed to come with
+        // `saveWorkflow`. Promotion publishes what it saves, so a store that has the
+        // save and not the transition would narrow cleanly here and then fail one
+        // call later, in the middle of an apply that has already written types and
+        // transforms into the target.
+        typeof store.publishWorkflow === 'function');
 }
 function supportsWorkflowStages(store) {
     return typeof store.writeStage === 'function' && typeof store.readStage === 'function';

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

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

package/dist/catalog.registry.d.ts

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