@dudousxd/nestjs-catalog 0.28.0 → 0.30.0

package/dist/catalog.pipeline.d.ts

@@ -3872,14 +3872,36 @@ export declare function readWorkflowCallOutput(value: unknown): WorkflowCallOutp
  */
 export interface CallableWorkflowRef {
     name: string;
+    /**
+     * How strong the fleet's claim about this entry is, mirroring durable core's
+     * `AnnouncementEvidence` rather than re-deriving it.
+     *
+     * - `'declared'` — a live worker published a descriptor naming this workflow,
+     *   so everything populated here was stated by that worker.
+     * - `'observed'` — nobody described it. What exists is a live routing token of
+     *   this name, which is exactly the condition convention routing uses, so the
+     *   name IS reachable — and nothing else is known: no version, no origin, no
+     *   runtime, and no assurance the token serves a workflow rather than a step
+     *   handler of the same name. A live queue, not a promise.
+     *
+     * Carried because the two tiers answer a question a picker cannot otherwise
+     * put: **will a pin on this name mean anything?** An `'observed'` entry never
+     * declares a version, so a version typed against it is compared, at run time,
+     * against the engine's routing default — the run comes back tagged
+     * `version:undeclared` and `checkCall` reports the pin as unverified rather
+     * than kept. Absent when the deployment answering predates the distinction.
+     */
+    evidence?: 'declared' | 'observed';
     /**
      * The version to pin, and **absent is a real answer**.
      *
      * A worker that has not been upgraded announces a bare name with no version
-     * and no group. Silence is not a claim, so no version is invented for it from
-     * another announcer's — and an entry without one cannot satisfy the pin, which
-     * is why {@link callableWorkflowBlock} refuses it rather than letting a picker
-     * offer a name that would run whatever is newest on the day it runs.
+     * and no group — or announces nothing at all and is here on its heartbeat
+     * alone ({@link evidence} `'observed'`). Silence is not a claim, so no version
+     * is invented for it from another announcer's — and an entry without one
+     * cannot satisfy the pin, which is why {@link callableWorkflowBlock} refuses
+     * it rather than letting a picker offer a name that would run whatever is
+     * newest on the day it runs.
      */
     version?: string;
     /** What it does, if the deployment publishes one. Shown beside the name. */
@@ -3931,11 +3953,17 @@ export interface CallableWorkflowDisagreement {
  * Two refusals, and they are refusals rather than warnings because in both cases
  * committing the entry would write a node whose meaning nobody can state:
  *
- * - `no-version` — an un-upgraded worker announced a bare name. The call node's
- *   whole point is the pin; a node holding a name and no version follows
- *   whatever gets deployed next, which is the failure the version field exists
- *   to prevent. The name is still perfectly typeable by hand *with* a version
- *   the author knows, so this refuses the one-click commit and not the workflow.
+ * - `no-version` — nothing live states a version for this name, either because an
+ *   un-upgraded worker announced a bare name or because nobody described it at
+ *   all and it is here on its heartbeat ({@link CallableWorkflowRef.evidence}
+ *   `'observed'`). The call node's whole point is the pin; a node holding a name
+ *   and no version follows whatever gets deployed next, which is the failure the
+ *   version field exists to prevent. The name is still perfectly typeable by hand
+ *   *with* a version the author knows — and the message says what that costs,
+ *   because a version typed against a callee that declares none is compared at run
+ *   time against the engine's routing default and comes back reported as
+ *   unverified, not as kept. That is the one thing an author choosing a pin from
+ *   this list could not otherwise find out until a load ran.
  * - `ambiguous-group` — two live workers claim this exact `name@version` from
  *   different groups. Two groups means two queues, and nothing here can know
  *   which one a run would land on, so the two bodies may not even be the same

package/dist/catalog.pipeline.js

@@ -2381,9 +2381,16 @@ function describeCount(value) {
 function callableWorkflowBlock(ref) {
     const version = typeof ref.version === 'string' ? ref.version.trim() : '';
     if (version.length === 0) {
+        // The two tiers differ in what they can even be asked, so they get their own
+        // sentence rather than one that fits neither: an `'observed'` entry has no
+        // descriptor at all behind it, and calling that "not upgraded to publish its
+        // registrations in full" would overstate what was seen.
+        const seen = ref.evidence === 'observed'
+            ? `Nothing describes "${ref.name}" — it is here because a live queue of that name exists, which is what an engine routes a call on and all it knows. No version, no origin and no runtime were stated, and not even that the queue serves a workflow rather than a step handler of the same name.`
+            : `A live worker announces "${ref.name}" without saying which version it runs, which is what a worker announces before it has been upgraded to publish its registrations in full.`;
         return {
             code: 'no-version',
-            message: `A live worker announces "${ref.name}" without saying which version it runs, which is what a worker announces before it has been upgraded to publish its registrations in full. A name with no version cannot be pinned, so this cannot be chosen — type the name and the version you mean.`,
+            message: `${seen} A name with no version cannot be pinned, so this cannot be chosen — type the name and the version you mean. Be aware of what that pin is worth: with nothing declaring a version, a run of it carries the engine's routing default and the load reports the pin as unverified rather than kept, until the worker serving it publishes one.`,
         };
     }
     const groups = ref.disagreements?.find((entry) => entry.axis === 'group')?.values ?? [];

package/dist/catalog.registry.js

@@ -23,10 +23,11 @@ const catalog_events_1 = require("./catalog.events");
 const catalog_options_1 = require("./catalog.options");
 const catalog_overlay_store_token_1 = require("./catalog.overlay-store.token");
 const catalog_registry_base_1 = require("./catalog.registry.base");
-const RELATION_KINDS = ['1:1', '1:m', 'm:1', 'm:n'];
-function isRelationKind(kind) {
-    return RELATION_KINDS.includes(kind);
-}
+// The one list of the four kinds, shared with the stored registry's read-time
+// narrowing and the publish route's refusal. This file used to hold its own
+// copy — three copies of a closed set, and the one here needed a cast to check
+// against it.
+const catalog_types_1 = require("./catalog.types");
 /**
  * Which end of the link holds the key.
  *
@@ -318,7 +319,7 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
             const fromDecorator = declaredProps[prop.name];
             const fromOverlay = overlayProps[prop.name];
             const { displayName, description, hidden, order } = resolveFieldPresentation(prop.name, index, fromDecorator, fromOverlay);
-            if (isRelationKind(prop.kind)) {
+            if ((0, catalog_types_1.isRelationKind)(prop.kind)) {
                 const targetType = prop.targetMeta?.className ?? String(prop.type);
                 relations.push({
                     name: prop.name,

package/dist/catalog.types.d.ts

@@ -17,7 +17,28 @@
  */
 import type { CatalogFilterOperator } from './catalog.filters';
 export type ScalarType = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'uuid' | 'unknown';
-export type RelationKind = '1:1' | '1:m' | 'm:1' | 'm:n';
+/**
+ * The four shapes a link can have. **One list, and everything that needs to
+ * know the four reads it.**
+ *
+ * A const rather than a bare union because two places have to decide whether a
+ * *runtime* string is one of them, and until this existed they each held their
+ * own copy of the four: the stored registry narrows what came out of a JSON
+ * column on the way to a def, and the publish path refuses a payload that names
+ * a kind nothing can draw. Two copies of a closed set is the shape of a bug
+ * where a fifth kind is added to one of them, and the symptom is a link that
+ * publishes cleanly and then renders as something else entirely.
+ */
+export declare const RELATION_KINDS: readonly ["1:1", "1:m", "m:1", "m:n"];
+export type RelationKind = (typeof RELATION_KINDS)[number];
+/**
+ * Whether a runtime value is one of the four.
+ *
+ * Same shape as {@link isReusableNodeKind} in `catalog.pipeline.ts` and for the
+ * same reason: a narrowing that reads the list rather than restating it cannot
+ * disagree with the list.
+ */
+export declare function isRelationKind(value: unknown): value is RelationKind;
 /** A single scalar field on an object type. */
 export interface CatalogPropertyDef {
     /** Code name, as written in the entity. Stable — the overlay never changes it. */

package/dist/catalog.types.js

@@ -17,3 +17,28 @@
  *    it safe to hand the editor to a non-engineer.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELATION_KINDS = void 0;
+exports.isRelationKind = isRelationKind;
+/**
+ * The four shapes a link can have. **One list, and everything that needs to
+ * know the four reads it.**
+ *
+ * A const rather than a bare union because two places have to decide whether a
+ * *runtime* string is one of them, and until this existed they each held their
+ * own copy of the four: the stored registry narrows what came out of a JSON
+ * column on the way to a def, and the publish path refuses a payload that names
+ * a kind nothing can draw. Two copies of a closed set is the shape of a bug
+ * where a fifth kind is added to one of them, and the symptom is a link that
+ * publishes cleanly and then renders as something else entirely.
+ */
+exports.RELATION_KINDS = ['1:1', '1:m', 'm:1', 'm:n'];
+/**
+ * Whether a runtime value is one of the four.
+ *
+ * Same shape as {@link isReusableNodeKind} in `catalog.pipeline.ts` and for the
+ * same reason: a narrowing that reads the list rather than restating it cannot
+ * disagree with the list.
+ */
+function isRelationKind(value) {
+    return exports.RELATION_KINDS.some((kind) => kind === value);
+}

package/dist/index.d.ts

@@ -26,4 +26,5 @@ export * from './catalog.filters';
 export { assertNoColumnCollisions, assertSafeIdentifier, CATALOG_RESERVED_COLUMNS, CATALOG_SNAPSHOT_MODES, CATALOG_STORE, type CarryForwardResult, type CatalogColumnCollision, CatalogColumnCollisionError, type CatalogFilteringReadStore, supportsObjectFilters, type CatalogMergeStore, type CatalogReadQuery, type CatalogReadResult, type CatalogReadStore, type CatalogReservedColumn, type CatalogSnapshotMode, type CatalogSnapshotStreamStore, type CatalogStoreCapabilities, type CatalogWriteStore, type ColumnCollisionOptions, findColumnCollisions, isCatalogStoreCapabilities, isReservedColumn, isSafeIdentifier, isWriteStore, outputAlias, physicalColumn, type SnapshotRef, supportsCarryForward, supportsSnapshotStreams, UnsafeIdentifierError, } from './catalog.store';
 export { MikroOrmReadStore } from './stores/mikro-orm-read.store';
 export type { CatalogGraph, CatalogObjectPage, CatalogObjectQuery, CatalogObjectTypeDef, CatalogOverlay, CatalogPropertyDef, CatalogRelationDef, CatalogSnapshot, RelationKind, ScalarType, } from './catalog.types';
+export { isRelationKind, RELATION_KINDS } from './catalog.types';
 export { REQUIRED_SCOPES, REQUIRES_HUMAN, RequireHuman, RequireScopes, } from './catalog.route-auth';

package/dist/index.js

@@ -18,7 +18,7 @@ exports.unreachableReusableNodeKind = exports.reusableNodeBodyOf = exports.REUSA
 exports.WORKFLOW_NODE_HEIGHT = exports.WORKFLOW_ISSUE_CODES = exports.WORKFLOW_FILTER_PREDICATE_KINDS = exports.WORKFLOW_FILTER_OPERATORS = exports.WORKFLOW_FILTER_MAX_VALUES = exports.WORKFLOW_FILTER_MAX_DEPTH = exports.WORKFLOW_FILTER_COLUMN_PATTERN = exports.WORKFLOW_EXECUTION_MODES = exports.WORKFLOW_COLUMN_GAP = exports.WORKFLOW_CALL_MODES = exports.WORKFLOW_CALL_CONTRACT = exports.WORKFLOW_BRANCH_LABELS = exports.validateWorkflow = exports.unreachableRenameUnnamed = exports.unreachableLookupUnmatched = exports.unreachablePredicateKind = exports.unreachableNodeKind = exports.unreachableConnectorKind = exports.unreachableCallMode = exports.unreachableFilterPredicateKind = exports.unreachableTransformMode = exports.unreachableFilterOperator = exports.transformMode = exports.recordModeRefusal = exports.TRANSFORM_MODES = exports.TRANSFORM_LANGUAGES = exports.TRANSFORM_RUNNER = exports.supportsStagePayloads = exports.supportsWorkflowStages = exports.supportsWorkflows = exports.supportsWorkflowReleases = exports.liveWorkflowVersion = exports.isWorkflowStatus = exports.isWorkflowSkipReason = exports.isWorkflowRenameUnnamed = exports.isWorkflowRenameColumns = exports.isWorkflowLookupUnmatched = exports.isWorkflowLookupFields = exports.isWorkflowPredicateKind = exports.isWorkflowNodeKind = exports.isWorkflowCallMode = exports.isWorkflowNode = exports.isWorkflowIfPredicate = exports.isWorkflowFilterValue = exports.isWorkflowFilterPredicateKind = exports.isWorkflowFilterPredicate = exports.isWorkflowFilterOperator = exports.isWorkflowExecutionMode = exports.isWorkflowEdge = exports.isWorkflowBranchLabel = void 0;
 exports.aggregateInputColumns = exports.AggregateTable = exports.workflowAggregateSeparator = exports.workflowAggregateOutputColumns = exports.workflowAggregateNeedsColumn = exports.workflowAggregateMaxGroups = exports.workflowAggregateJoinMaxLength = exports.workflowAggregateColumns = exports.WORKFLOW_AGGREGATE_MAX_SEPARATOR = exports.WORKFLOW_AGGREGATE_MAX_GROUPS = exports.WORKFLOW_AGGREGATE_MAX_GROUP_BY = exports.WORKFLOW_AGGREGATE_MAX_AGGREGATES = exports.WORKFLOW_AGGREGATE_JOIN_MAX_LENGTH = exports.WORKFLOW_AGGREGATE_JOIN_LENGTH_CEILING = exports.WORKFLOW_AGGREGATE_GROUPS_CEILING = exports.WORKFLOW_AGGREGATE_FUNCTIONS = exports.WORKFLOW_AGGREGATE_DEFAULT_SEPARATOR = exports.unreachableAggregateFunction = exports.isWorkflowAggregates = exports.isWorkflowAggregateFunction = exports.aggregateRefusals = exports.workflowRenameUnnamed = exports.renameColumnRefusals = exports.WORKFLOW_LOOKUP_UNMATCHED = exports.WORKFLOW_LOOKUP_MAX_REFERENCE_ROWS = exports.WORKFLOW_LOOKUP_MAX_FIELDS = exports.workflowLookupUnmatched = exports.workflowLookupKey = exports.workflowLookupColumns = exports.lookupConfigRefusals = exports.workflowRunOrder = exports.workflowNodeRuns = exports.workflowSourceObjectType = exports.workflowNarrowedTypes = exports.workflowKnownColumns = exports.workflowGraphHash = exports.workflowFilterMatches = exports.workflowFilterColumns = exports.workflowCallMode = exports.workflowRowY = exports.workflowColumnX = exports.WORKFLOW_STATUSES = exports.WORKFLOW_SKIP_REASONS = exports.WORKFLOW_ROW_GAP = exports.WORKFLOW_RENAME_UNNAMED = exports.WORKFLOW_RENAME_MAX_COLUMNS = exports.WORKFLOW_PREDICATE_KINDS = exports.WORKFLOW_NODE_WIDTH = exports.WORKFLOW_NODE_KINDS = exports.WORKFLOW_NODE_ID_PATTERN = void 0;
 exports.CATALOG_RESERVED_COLUMNS = exports.assertSafeIdentifier = 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.supportsSavedQueryRevisions = exports.isWorkspaceStore = exports.isTraceStore = exports.isCatalogTraceOutcome = exports.embeddedVisualization = exports.CATALOG_WORKSPACE_STORE = exports.CATALOG_TRACE_STORE = exports.CATALOG_TRACE_OUTCOMES = exports.CATALOG_REVISION_LIMIT = exports.visibleToPrincipal = exports.searchCatalog = exports.maySearch = exports.emptySearch = exports.bestMatch = exports.MAX_SEARCH_LIMIT = exports.DEFAULT_SEARCH_LIMIT = exports.CatalogService = exports.transformShapeHint = exports.transformShape = exports.transformDeclaresModule = exports.SubprocessTransformRunner = exports.toCsv = exports.guardFormula = exports.csvLines = exports.csvCell = exports.QueryCache = exports.renameStagePayload = exports.isColumnarStageBatch = exports.encodeStageRows = exports.decodeStageRows = exports.classifyStagePayload = exports.STAGE_ENCODING_VERSION = exports.STAGE_ENCODING = exports.WorkflowAggregateError = void 0;
-exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.MikroOrmReadStore = exports.UnsafeIdentifierError = exports.supportsSnapshotStreams = exports.supportsCarryForward = exports.physicalColumn = exports.outputAlias = exports.isWriteStore = exports.isSafeIdentifier = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.supportsObjectFilters = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = void 0;
+exports.RequireScopes = exports.RequireHuman = exports.REQUIRES_HUMAN = exports.REQUIRED_SCOPES = exports.RELATION_KINDS = exports.isRelationKind = exports.MikroOrmReadStore = exports.UnsafeIdentifierError = exports.supportsSnapshotStreams = exports.supportsCarryForward = exports.physicalColumn = exports.outputAlias = exports.isWriteStore = exports.isSafeIdentifier = exports.isReservedColumn = exports.isCatalogStoreCapabilities = exports.findColumnCollisions = exports.supportsObjectFilters = exports.CatalogColumnCollisionError = exports.CATALOG_STORE = exports.CATALOG_SNAPSHOT_MODES = 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; } });
@@ -310,6 +310,9 @@ Object.defineProperty(exports, "supportsSnapshotStreams", { enumerable: true, ge
 Object.defineProperty(exports, "UnsafeIdentifierError", { enumerable: true, get: function () { return catalog_store_1.UnsafeIdentifierError; } });
 var mikro_orm_read_store_1 = require("./stores/mikro-orm-read.store");
 Object.defineProperty(exports, "MikroOrmReadStore", { enumerable: true, get: function () { return mikro_orm_read_store_1.MikroOrmReadStore; } });
+var catalog_types_1 = require("./catalog.types");
+Object.defineProperty(exports, "isRelationKind", { enumerable: true, get: function () { return catalog_types_1.isRelationKind; } });
+Object.defineProperty(exports, "RELATION_KINDS", { enumerable: true, get: function () { return catalog_types_1.RELATION_KINDS; } });
 var catalog_route_auth_1 = require("./catalog.route-auth");
 Object.defineProperty(exports, "REQUIRED_SCOPES", { enumerable: true, get: function () { return catalog_route_auth_1.REQUIRED_SCOPES; } });
 Object.defineProperty(exports, "REQUIRES_HUMAN", { enumerable: true, get: function () { return catalog_route_auth_1.REQUIRES_HUMAN; } });

package/package.json

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