@dereekb/dbx-cli 14.1.0 → 14.2.0

package/lint-cache/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@dereekb/dbx-cli-lint-cache",
-  "version": "14.1.0",
+  "version": "14.2.0",
+  "sideEffects": false,
   "private": true,
   "type": "module",
   "devDependencies": {
@@ -8,7 +9,7 @@
     "eslint": "10.9.1"
   },
   "peerDependencies": {
-    "@dereekb/util": "14.1.0",
+    "@dereekb/util": "14.2.0",
     "yargs": "^18.0.0"
   }
 }

package/manifest-extract/index.esm.js

@@ -696,6 +696,10 @@ var MCP_TOOL_NAME_SEGMENT_TAG = 'dbxModelMcpToolNameSegment';
 var MODEL_TYPE_VALUE_PATTERN = /^[a-z][A-Za-z0-9_$]*$/;
 var TOOL_NAME_SEGMENT_PATTERN = /^[A-Za-z][A-Za-z0-9_$]*$/;
 var IDENTITY_FN = 'firestoreModelIdentity';
+// the declared-type counterparts of IDENTITY_FN, which is all a .d.ts retains of the call
+var IDENTITY_TYPE = 'FirestoreModelIdentity';
+var ROOT_IDENTITY_TYPE = 'RootFirestoreModelIdentity';
+var IDENTITY_WITH_PARENT_TYPE = 'FirestoreModelIdentityWithParent';
 var SINGLE_ITEM_COLLECTION_FN = 'singleItemFirestoreCollection';
 var ROOT_SINGLE_ITEM_COLLECTION_FN = 'rootSingleItemFirestoreCollection';
 var SINGLE_ITEM_COLLECTION_FN_NAMES = [
@@ -763,13 +767,25 @@ function readIdentities(sourceFile) {
                 for(var _iterator1 = statement.getDeclarations()[Symbol.iterator](), _step1; !(_iteratorNormalCompletion1 = (_step1 = _iterator1.next()).done); _iteratorNormalCompletion1 = true){
                     var decl = _step1.value;
                     var initializer = decl.getInitializer();
-                    if (!initializer || !Node.isCallExpression(initializer)) continue;
-                    if (initializer.getExpression().getText() !== IDENTITY_FN) continue;
-                    var parsed = parseFirestoreModelIdentityArgs(initializer.getArguments());
-                    if (parsed) {
-                        out.push(_object_spread({
-                            identityConst: decl.getName()
-                        }, parsed));
+                    if (initializer && Node.isCallExpression(initializer)) {
+                        if (initializer.getExpression().getText() !== IDENTITY_FN) continue;
+                        var parsed = parseFirestoreModelIdentityArgs(initializer.getArguments());
+                        if (parsed) {
+                            out.push(_object_spread_props(_object_spread({
+                                identityConst: decl.getName()
+                            }, parsed), {
+                                parentModelType: undefined
+                            }));
+                        }
+                    } else {
+                        // A declaration file has no initializer to read — the identity survives only in the declared
+                        // type, which is the whole reason a node_modules-installed package can contribute models at all.
+                        var parsed1 = parseDeclaredIdentityType(decl.getTypeNode());
+                        if (parsed1) {
+                            out.push(_object_spread({
+                                identityConst: decl.getName()
+                            }, parsed1));
+                        }
                     }
                 }
             } catch (err) {
@@ -803,6 +819,96 @@ function readIdentities(sourceFile) {
     }
     return out;
 }
+/**
+ * Reads an identity out of the DECLARED TYPE of an initializer-less export.
+ *
+ * The three shapes `@dereekb/firebase` declares, after a `.d.ts` rewrites every import as an inline
+ * `import("…").` qualifier:
+ *
+ * - `RootFirestoreModelIdentity<"worker", "wk">`
+ * - `FirestoreModelIdentity<"worker", "wk">`
+ * - `FirestoreModelIdentityWithParent<RootFirestoreModelIdentity<"prompt", "orp">, "version", "orpv">`
+ *
+ * @param typeNode - The declared type node, when the declaration carries one.
+ * @returns The identity parts, or undefined when the type is not one of the identity shapes.
+ */ function parseDeclaredIdentityType(typeNode) {
+    var result;
+    var named = readNamedTypeNode(typeNode);
+    if (named) {
+        var typeName = named.typeName, args = named.args;
+        if (typeName === IDENTITY_WITH_PARENT_TYPE && args.length >= 3) {
+            var _readLiteralTypeText;
+            var parent = parseDeclaredIdentityType(args[0]);
+            result = {
+                modelType: (_readLiteralTypeText = readLiteralTypeText(args[1])) !== null && _readLiteralTypeText !== void 0 ? _readLiteralTypeText : '',
+                collectionPrefix: readLiteralTypeText(args[2]),
+                parentIdentityConst: undefined,
+                parentModelType: parent === null || parent === void 0 ? void 0 : parent.modelType
+            };
+        } else if ((typeName === ROOT_IDENTITY_TYPE || typeName === IDENTITY_TYPE) && args.length >= 2) {
+            var _readLiteralTypeText1;
+            result = {
+                modelType: (_readLiteralTypeText1 = readLiteralTypeText(args[0])) !== null && _readLiteralTypeText1 !== void 0 ? _readLiteralTypeText1 : '',
+                collectionPrefix: readLiteralTypeText(args[1]),
+                parentIdentityConst: undefined,
+                parentModelType: undefined
+            };
+        }
+        // a default-parameterized identity carries no literals, so it names no model
+        if (result && !result.modelType) {
+            result = undefined;
+        }
+    }
+    return result;
+}
+/**
+ * Normalizes a type node to its name and type arguments.
+ *
+ * Two shapes, because a `.d.ts` does not write the one the source did: source that imported the type
+ * normally leaves a `TypeReference` (`RootFirestoreModelIdentity<…>`), while a declaration file inlines
+ * the import and leaves an `ImportType` (`import("@dereekb/firebase").RootFirestoreModelIdentity<…>`),
+ * whose name is its QUALIFIER rather than its type name. Reading only the first is what made a
+ * declaration-sourced identity invisible.
+ *
+ * @param typeNode - The type node to read.
+ * @returns The unqualified type name and its type arguments, or undefined when the node is neither shape.
+ */ function readNamedTypeNode(typeNode) {
+    var result;
+    if (typeNode) {
+        if (Node.isImportTypeNode(typeNode)) {
+            var qualifier = typeNode.getQualifier();
+            if (qualifier) {
+                var _qualifier_getText_split_pop;
+                result = {
+                    typeName: (_qualifier_getText_split_pop = qualifier.getText().split('.').pop()) !== null && _qualifier_getText_split_pop !== void 0 ? _qualifier_getText_split_pop : '',
+                    args: typeNode.getTypeArguments()
+                };
+            }
+        } else if (Node.isTypeReference(typeNode)) {
+            var _typeNode_getTypeName_getText_split_pop;
+            result = {
+                typeName: (_typeNode_getTypeName_getText_split_pop = typeNode.getTypeName().getText().split('.').pop()) !== null && _typeNode_getTypeName_getText_split_pop !== void 0 ? _typeNode_getTypeName_getText_split_pop : '',
+                args: typeNode.getTypeArguments()
+            };
+        }
+    }
+    return result;
+}
+/**
+ * Reads the text of a string-literal type node (`"wk"` → `wk`).
+ *
+ * @param node - The type node to read.
+ * @returns The literal's text, or undefined when the node is not a string literal type.
+ */ function readLiteralTypeText(node) {
+    var result;
+    if (node && Node.isLiteralTypeNode(node)) {
+        var literal = node.getLiteral();
+        if (Node.isStringLiteral(literal)) {
+            result = literal.getLiteralText();
+        }
+    }
+    return result;
+}
 function readInterfaces(sourceFile) {
     var out = [];
     var _iteratorNormalCompletion = true, _didIteratorError = false, _iteratorError = undefined;

package/manifest-extract/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@dereekb/dbx-cli/manifest-extract",
-  "version": "14.1.0",
+  "version": "14.2.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.1.0",
-    "@dereekb/dbx-cli": "14.1.0",
-    "@dereekb/firebase": "14.1.0",
-    "@dereekb/model": "14.1.0",
-    "@dereekb/nestjs": "14.1.0",
-    "@dereekb/rxjs": "14.1.0",
-    "@dereekb/util": "14.1.0",
+    "@dereekb/date": "14.2.0",
+    "@dereekb/dbx-cli": "14.2.0",
+    "@dereekb/firebase": "14.2.0",
+    "@dereekb/model": "14.2.0",
+    "@dereekb/nestjs": "14.2.0",
+    "@dereekb/rxjs": "14.2.0",
+    "@dereekb/util": "14.2.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

package/manifest-extract/src/lib/types.d.ts

@@ -119,6 +119,16 @@ export interface ModelExtractionIdentity {
     readonly modelType: string;
     readonly collectionPrefix: string | undefined;
     readonly parentIdentityConst: string | undefined;
+    /**
+     * Model type of the parent, when the identity was read from a DECLARATION rather than a call.
+     *
+     * A `.d.ts` spells the parent as an inline type (`FirestoreModelIdentityWithParent<
+     * RootFirestoreModelIdentity<"openRouterPrompt", "orp">, …>`) rather than by naming the const the
+     * source called `firestoreModelIdentity` with, so the const name the parent chain is walked by is not
+     * present to read. The model type is, and it identifies the same parent — the orchestrator resolves
+     * one to the other against the global identity registry.
+     */
+    readonly parentModelType: string | undefined;
 }
 /**
  * One property on a `@dbxModel`-tagged interface.

package/model-test/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@dereekb/dbx-cli/model-test",
-  "version": "14.1.0",
+  "version": "14.2.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/util": "14.1.0",
+    "@dereekb/util": "14.2.0",
     "ts-morph": "^28.0.0"
   },
   "exports": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dereekb/dbx-cli",
-  "version": "14.1.0",
+  "version": "14.2.0",
   "type": "module",
   "sideEffects": false,
   "bin": {
@@ -66,11 +66,11 @@
     }
   },
   "peerDependencies": {
-    "@dereekb/date": "14.1.0",
-    "@dereekb/firebase": "14.1.0",
-    "@dereekb/model": "14.1.0",
-    "@dereekb/nestjs": "14.1.0",
-    "@dereekb/util": "14.1.0",
+    "@dereekb/date": "14.2.0",
+    "@dereekb/firebase": "14.2.0",
+    "@dereekb/model": "14.2.0",
+    "@dereekb/nestjs": "14.2.0",
+    "@dereekb/util": "14.2.0",
     "@nestjs/common": "^12.0.1",
     "arktype": "^2.2.0",
     "firebase": "^12.18.0",

package/route/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@dereekb/dbx-cli/route",
-  "version": "14.1.0",
+  "version": "14.2.0",
   "type": "module",
   "sideEffects": false,
   "peerDependencies": {
-    "@dereekb/date": "14.1.0",
-    "@dereekb/dbx-cli": "14.1.0",
-    "@dereekb/firebase": "14.1.0",
-    "@dereekb/model": "14.1.0",
-    "@dereekb/nestjs": "14.1.0",
-    "@dereekb/util": "14.1.0"
+    "@dereekb/date": "14.2.0",
+    "@dereekb/dbx-cli": "14.2.0",
+    "@dereekb/firebase": "14.2.0",
+    "@dereekb/model": "14.2.0",
+    "@dereekb/nestjs": "14.2.0",
+    "@dereekb/util": "14.2.0"
   },
   "exports": {
     "./package.json": "./package.json",

package/src/lib/cache/cache.command.factory.d.ts

@@ -0,0 +1,44 @@
+import { type Maybe } from '@dereekb/util';
+import type { CommandModule } from 'yargs';
+import { type CliDataCache } from './data-cache';
+/**
+ * Default command name for the data-cache management command.
+ */
+export declare const DEFAULT_CLI_DATA_CACHE_COMMAND_NAME = "cache";
+export interface CreateCacheCommandInput {
+    readonly cliName: string;
+    /**
+     * Override for the cache the command manages. Defaults to the CLI's own
+     * `<configDir>/cache` directory.
+     */
+    readonly cache?: Maybe<CliDataCache>;
+    /**
+     * The current CLI build stamp. When supplied, `cache list` marks entries recorded by a different
+     * build, which is the one staleness signal the fingerprint deliberately does not cover.
+     */
+    readonly cliBuildStamp?: Maybe<string>;
+    readonly commandName?: string;
+}
+/**
+ * Factory for the `cache` command.
+ *
+ * Registered as a CONFIG command, not an API command: inspecting or clearing a LOCAL cache must work
+ * offline and without a token — which is precisely the situation in which a cache matters. Mirrors
+ * the `firestore-queries` (config) vs `firestore-query` (api) split.
+ *
+ * Subcommands:
+ * - `cache list [--env <env>] [--dataset <id>] [--json]`
+ * - `cache show <dataset> [--env <env>] [--fingerprint <fp>] [--data]`
+ * - `cache clear [--env <env>] [--dataset <id>] [--all]`
+ * - `cache prune --older-than <hours> [--env <env>] [--dataset <id>]`
+ *
+ * @param input - Factory configuration.
+ * @param input.cliName - The CLI's binary name, used to derive the default cache directory.
+ * @param input.cache - Optional cache override (tests point this at a temp dir).
+ * @param input.cliBuildStamp - The current build stamp, for marking entries from another build.
+ * @param input.commandName - Optional command-name override.
+ * @returns A yargs `CommandModule` for `runCli({ configCommands })`.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCacheCommand(input: CreateCacheCommandInput): CommandModule;

package/src/lib/cache/data-cache.codec.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Error code thrown when a value handed to {@link toCliCacheJson} contains a reference cycle.
+ */
+export declare const CLI_DATA_CACHE_CYCLE_ERROR_CODE = "CLI_DATA_CACHE_CYCLE";
+/**
+ * Error code thrown when a value handed to {@link toCliCacheJson} holds something that cannot be
+ * persisted and re-read at all — a function or a symbol.
+ */
+export declare const CLI_DATA_CACHE_UNSUPPORTED_VALUE_ERROR_CODE = "CLI_DATA_CACHE_UNSUPPORTED_VALUE";
+/**
+ * Converts a value into a JSON-safe tree, tagging the types a plain `JSON.stringify` round trip
+ * would lose.
+ *
+ * This is a PRE-WALK rather than a `JSON.stringify` replacer, and that is load-bearing:
+ * `Date.prototype.toJSON` runs BEFORE a replacer sees the value, so a replacer is handed an ISO
+ * string and cannot tell a `Date` from a string that merely looks like one. Every model in a
+ * dbx-components app persists its dates through `firestoreDate` (an ISO string on the wire, a live
+ * `Date` in memory), so that distinction is the whole problem.
+ *
+ * Handled: `Date`, `Map`, `Set`, `undefined`, non-finite numbers, `bigint`, arrays, plain objects,
+ * and the JSON primitives. A class instance that is none of the above is FLATTENED to its own
+ * enumerable properties — the one lossy case, and the reason a stage whose output holds a class
+ * instance must supply its own codec.
+ *
+ * @param value - The value to encode.
+ * @returns A tree containing only values `JSON.stringify` renders losslessly.
+ * @throws {CliError} On a reference cycle, or on a function/symbol anywhere in the tree.
+ */
+export declare function toCliCacheJson(value: unknown): unknown;
+/**
+ * Rebuilds a value encoded by {@link toCliCacheJson}, restoring the tagged types.
+ *
+ * @param raw - The JSON-parsed tree written by {@link toCliCacheJson}.
+ * @returns The decoded value.
+ */
+export declare function fromCliCacheJson(raw: unknown): unknown;

package/src/lib/cache/data-cache.d.ts

@@ -0,0 +1,272 @@
+import { type ArrayOrValue, type Maybe, type Milliseconds } from '@dereekb/util';
+import { type CliDataCacheOptions } from './data-cache.options';
+/**
+ * Version of the on-disk index and payload envelopes.
+ *
+ * Bumped when the envelope shape itself changes. A payload written under a different schema version
+ * is a miss, not an error — see {@link CliDataCache.loadData}.
+ */
+export declare const CLI_DATA_CACHE_SCHEMA_VERSION = 1;
+/**
+ * Name of the index file inside the cache directory.
+ */
+export declare const CLI_DATA_CACHE_INDEX_FILE_NAME = "index.json";
+/**
+ * One recorded build of one dataset, as held in the index.
+ *
+ * The payload lives in its own file (see {@link file}) so listing the cache never has to read the
+ * data — mirroring the lint cache's per-project files plus an index roll-up.
+ */
+export interface CliDataCacheEntry {
+    /**
+     * Identifier of the cached pipeline stage, e.g. `worker.lineDetails`.
+     */
+    readonly dataset: string;
+    /**
+     * The stage version this build was produced by. An entry whose version no longer matches the
+     * caller's is a miss.
+     */
+    readonly datasetVersion: number;
+    /**
+     * The env the data was read from.
+     */
+    readonly env: string;
+    readonly fingerprint: string;
+    /**
+     * The NORMALIZED filter this build covers, stored verbatim so `cache list` can show what an entry
+     * is a build OF rather than just its digest.
+     */
+    readonly filter: unknown;
+    /**
+     * When the build was recorded, as an ISO string.
+     */
+    readonly builtAt: string;
+    /**
+     * Number of rows, when the cached value was an array. Absent for a non-array payload.
+     */
+    readonly itemCount?: Maybe<number>;
+    /**
+     * Size of the payload file in bytes.
+     */
+    readonly bytes: number;
+    /**
+     * Absolute path of the payload file.
+     */
+    readonly file: string;
+    /**
+     * The CLI build that produced the entry, when known.
+     *
+     * Recorded but deliberately NOT part of the fingerprint: fingerprinting on it would invalidate the
+     * whole cache on every rebuild of the CLI, which is exactly the workflow this feature is meant to
+     * speed up. `cache list` surfaces it so an entry from a different build is visible.
+     */
+    readonly cliBuildStamp?: Maybe<string>;
+}
+/**
+ * The persisted payload envelope.
+ */
+export interface CliDataCachePayloadFile {
+    readonly schemaVersion: number;
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    readonly fingerprint: string;
+    readonly builtAt: string;
+    /**
+     * The cached value, encoded by the entry's codec.
+     */
+    readonly payload: unknown;
+}
+/**
+ * How a cached value is converted to and from the JSON written on disk.
+ *
+ * Defaults to the tagged structured codec, which needs no per-dataset work. A dataset whose value
+ * holds something the tagged codec cannot represent — a class instance whose identity matters —
+ * supplies its own.
+ */
+export interface CliDataCacheCodec<T> {
+    readonly toJson: (data: T) => unknown;
+    readonly fromJson: (raw: unknown) => T;
+}
+/**
+ * The default codec: the tagged structured JSON walk.
+ */
+export declare const DEFAULT_CLI_DATA_CACHE_CODEC: CliDataCacheCodec<any>;
+/**
+ * Narrowing filter accepted by {@link CliDataCache.listEntries} and {@link CliDataCache.removeEntries}.
+ */
+export interface CliDataCacheEntryFilter {
+    readonly env?: Maybe<string>;
+    readonly dataset?: Maybe<string>;
+    readonly fingerprint?: Maybe<string>;
+    /**
+     * Keep only entries built longer ago than this. Used by `cache prune`.
+     */
+    readonly olderThanMs?: Maybe<Milliseconds>;
+}
+/**
+ * Input for {@link CliDataCache.saveData}.
+ */
+export interface SaveCliDataCacheInput<T> {
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    readonly filter?: Maybe<unknown>;
+    readonly data: T;
+    readonly codec?: Maybe<CliDataCacheCodec<T>>;
+}
+/**
+ * Input for {@link CliDataCache.loadData}.
+ */
+export interface LoadCliDataCacheInput<T> {
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    readonly filter?: Maybe<unknown>;
+    readonly codec?: Maybe<CliDataCacheCodec<T>>;
+    /**
+     * Reject an entry built longer ago than this. Omit for no age limit.
+     */
+    readonly maxAgeMs?: Maybe<Milliseconds>;
+}
+/**
+ * A hit returned by {@link CliDataCache.loadData}.
+ */
+export interface CliDataCacheHit<T> {
+    readonly data: T;
+    readonly entry: CliDataCacheEntry;
+}
+/**
+ * On-disk store of recorded dataset builds.
+ */
+export interface CliDataCache {
+    /**
+     * The directory holding the index and every payload file.
+     */
+    readonly dataCacheDir: string;
+    /**
+     * Returns every recorded entry matching `filter`, newest build first.
+     */
+    listEntries(filter?: Maybe<CliDataCacheEntryFilter>): Promise<CliDataCacheEntry[]>;
+    /**
+     * Reads a recorded build, or `undefined` when there is no usable one.
+     *
+     * Any reason the entry cannot be used — absent, wrong `datasetVersion`, wrong schema version, past
+     * `maxAgeMs`, payload file missing, payload unparsable — is reported the same way: a miss, so the
+     * caller rebuilds. A cache is never allowed to turn into a failure.
+     */
+    loadData<T>(input: LoadCliDataCacheInput<T>): Promise<Maybe<CliDataCacheHit<T>>>;
+    /**
+     * Records a build, replacing any previous build of the same dataset + filter.
+     */
+    saveData<T>(input: SaveCliDataCacheInput<T>): Promise<CliDataCacheEntry>;
+    /**
+     * Removes every entry matching `filter` (and its payload file). Returns what was removed.
+     */
+    removeEntries(filter?: Maybe<CliDataCacheEntryFilter>): Promise<CliDataCacheEntry[]>;
+}
+export interface CreateCliDataCacheInput {
+    /**
+     * Directory holding the index and payload files, e.g. `~/.<cliName>/cache`.
+     */
+    readonly dataCacheDir: string;
+    /**
+     * Optional stamp identifying the CLI build, recorded on every entry it writes.
+     */
+    readonly cliBuildStamp?: Maybe<string>;
+}
+/**
+ * Creates the on-disk dataset cache.
+ *
+ * Layout, mirroring the lint cache's per-key files plus a versioned index roll-up:
+ *
+ * ```
+ * <dataCacheDir>/index.json                            the CliDataCacheEntry roll-up
+ * <dataCacheDir>/<env>/<dataset>/<fingerprint>.json    one CliDataCachePayloadFile per build
+ * ```
+ *
+ * Everything is written mode 0600. A cached export holds production rows — worker names, emails,
+ * billing lines — so the files are readable by the owning user only, the same posture as the token
+ * and Firestore-session caches next to them.
+ *
+ * @param input - The cache inputs.
+ * @param input.dataCacheDir - Directory holding the index and payload files.
+ * @param input.cliBuildStamp - Optional stamp identifying the CLI build, recorded on written entries.
+ * @returns The cache.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function createCliDataCache(input: CreateCliDataCacheInput): CliDataCache;
+/**
+ * Whether a recorded build is too old to satisfy a read.
+ *
+ * @param entry - The entry to test.
+ * @param maxAgeMs - The age limit. `null`/`undefined` means no limit.
+ * @returns Whether the entry is past the limit.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function isEntryExpired(entry: CliDataCacheEntry, maxAgeMs: Maybe<Milliseconds>): boolean;
+/**
+ * The outcome of {@link loadOrBuildCliCachedData}.
+ */
+export interface CliCachedDataResult<T> {
+    readonly data: T;
+    /**
+     * Whether `data` came off disk rather than from `build()`.
+     */
+    readonly fromCache: boolean;
+    readonly dataset: string;
+    readonly fingerprint: string;
+    readonly builtAt: Date;
+    /**
+     * How old the data is. Zero for a fresh build.
+     */
+    readonly ageMs: Milliseconds;
+    readonly itemCount?: Maybe<number>;
+}
+/**
+ * Input for {@link loadOrBuildCliCachedData}.
+ */
+export interface LoadOrBuildCliCachedDataInput<T> {
+    readonly cache: CliDataCache;
+    readonly dataset: string;
+    readonly datasetVersion: number;
+    readonly env: string;
+    /**
+     * The inputs this stage's contents depend on — and ONLY those. Anything applied after the stage
+     * (output format, export flavour, a row filter the pipeline applies downstream) must be left out,
+     * or changing it will needlessly miss.
+     */
+    readonly filter?: Maybe<unknown>;
+    /**
+     * The invocation's cache policy. Defaults to {@link DEFAULT_CLI_DATA_CACHE_OPTIONS} (record only).
+     */
+    readonly options?: Maybe<CliDataCacheOptions>;
+    readonly codec?: Maybe<CliDataCacheCodec<T>>;
+    /**
+     * Produces the data when no recorded build satisfies the run. Only called on a miss, which is what
+     * makes nesting these calls resolve a stage chain back-to-front: a hit on a late stage never runs
+     * the earlier stages at all.
+     */
+    readonly build: () => Promise<T>;
+}
+/**
+ * Reads a recorded build of a dataset, or produces and records one.
+ *
+ * @param input - The lookup + build inputs.
+ * @returns The data plus where it came from.
+ */
+export declare function loadOrBuildCliCachedData<T>(input: LoadOrBuildCliCachedDataInput<T>): Promise<CliCachedDataResult<T>>;
+/**
+ * Builds the `cache` provenance block for an output envelope's `meta`.
+ *
+ * Emitting it on every cached command is what lets a reader tell whether the bytes in front of them
+ * came off disk, and how old they are, without re-running anything.
+ *
+ * @param results - One result, or the per-stage results of a pipeline.
+ * @returns The meta block: one object for a single result, an array for several.
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare function cliDataCacheMeta(results: ArrayOrValue<CliCachedDataResult<unknown>>): Record<string, unknown>;