@dudousxd/nestjs-catalog 0.29.0 → 0.31.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.store.d.ts

@@ -9,6 +9,72 @@ import type { CatalogObjectQuery, CatalogObjectTypeDef } from './catalog.types';
  * the application's own tables, a separate warehouse schema, or a column store,
  * without the screens above it changing.
  */
+/**
+ * Where a snapshot's rows have been copied to, outside the database.
+ *
+ * **Vocabulary only — this package writes none of these and reads none of them.**
+ * It is declared here because it belongs on {@link SnapshotRef}, and a
+ * `SnapshotRef` is what every screen and every caller already holds. The
+ * machinery that produces an archive lives in
+ * `@dudousxd/nestjs-catalog-pipeline`, which is the package already allowed to
+ * know what a bucket is; the catalog itself stays unable to name one.
+ *
+ * ## What its presence means, and what it does not
+ *
+ * Present means *a verified copy of this snapshot exists at `path`*. It says
+ * nothing about whether the rows are still in the database — those are two
+ * independent facts and a caller that conflates them gets the dangerous reading
+ * in both directions. The three states a console has to tell apart are:
+ *
+ * - **no `archive`** — the snapshot is in the database and nowhere else.
+ * - **`archive` present, rows still in the table** — copied, not moved. Reads
+ *   are unchanged and cost what they always did.
+ * - **`archive` present, rows gone** — the snapshot lives in object storage.
+ *   Still readable, still identified, and **not** the same price as a read of a
+ *   hot snapshot. {@link bytes} is here so a screen can say which it is about
+ *   to do rather than presenting the two as one click.
+ *
+ * A snapshot with no `SnapshotRef` at all is the fourth state, and it is the
+ * only one that means *gone*.
+ */
+export interface SnapshotArchiveRef {
+    /** The only format written today. Named rather than assumed, so a second one can arrive. */
+    format: 'parquet';
+    /**
+     * The disk the bytes went to, when a host named one.
+     *
+     * Absent means `path` is resolved by whatever wrote it — a filesystem path in
+     * a test, a bucket a host configured. The disk is recorded rather than
+     * inferred because a deployment may mount several and "which one" is not
+     * recoverable from the path.
+     */
+    disk?: string;
+    /** The directory holding this snapshot's parts and its manifest, without a trailing slash. */
+    path: string;
+    /** Rows in the archive. Compared against the snapshot's own count when it was written. */
+    rowCount: number;
+    /** Size on the far end, for a screen that has to say what a read will cost. */
+    bytes: number;
+    /**
+     * SHA-256 over the row stream in `_row` order, as the manifest records it.
+     *
+     * A row count catches a truncated archive and nothing else: an archive with
+     * every row present and one value corrupted has exactly the right count. This
+     * is the check that fails for that, and it is only meaningful because the
+     * stream is ordered — see the store's `streamSnapshot`.
+     */
+    checksum: string;
+    writtenAt: string;
+    /**
+     * When the archive was last read back and found to match.
+     *
+     * Separate from {@link writtenAt} because they answer different questions and
+     * a caller about to delete rows needs the second one. Absent means written but
+     * not confirmed readable, which is exactly the state in which nothing may be
+     * deleted.
+     */
+    verifiedAt?: string;
+}
 /** A point-in-time view of one object type. */
 export interface SnapshotRef {
     /**
@@ -27,6 +93,14 @@ export interface SnapshotRef {
     principalId: string;
     /** Free-form provenance: which base, which file, which workflow run. */
     labels?: Record<string, string>;
+    /**
+     * Where this snapshot's rows have been copied to, if anywhere.
+     *
+     * Optional, and absent is the answer for every snapshot in every deployment
+     * that archives nothing — which is all of them until a host asks. See
+     * {@link SnapshotArchiveRef} for the three states its presence distinguishes.
+     */
+    archive?: SnapshotArchiveRef;
 }
 /**
  * How a store holds history. One list, so nothing narrows a stored or

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export { type AuditQuery, CATALOG_REVISION_LIMIT, CATALOG_TRACE_OUTCOMES, CATALO
 export { CATALOG_PRINCIPAL_RESOLVER, type CatalogActor, type CatalogGrants, type CatalogPrincipal, type CatalogPrincipalResolver, type CatalogScope, composePrincipalId, delegatePrincipal, expandScopes, hasScope, parsePrincipalId, PRINCIPAL_ACTOR_SEPARATOR, maySeeClassification, mayRead, mayWrite, readableObjectPage, StaticKeyPrincipalResolver, } from './catalog.principal';
 export * from './catalog.access';
 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 { 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 SnapshotArchiveRef, 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';

package/package.json

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