@forzalabs/remora 2.0.1 → 2.0.3

package/index.js

@@ -7759,15 +7759,15 @@ var require_index_cjs = __commonJS({
       };
     }
     function wrapConversion(toModel, graph2) {
-      const path29 = [graph2[toModel].parent, toModel];
+      const path30 = [graph2[toModel].parent, toModel];
       let fn = convert$1[graph2[toModel].parent][toModel];
       let cur = graph2[toModel].parent;
       while (graph2[cur].parent) {
-        path29.unshift(graph2[cur].parent);
+        path30.unshift(graph2[cur].parent);
         fn = link(convert$1[graph2[cur].parent][cur], fn);
         cur = graph2[cur].parent;
       }
-      fn.conversion = path29;
+      fn.conversion = path30;
       return fn;
     }
     function route(fromModel) {
@@ -8397,7 +8397,7 @@ var require_node2 = __commonJS({
 var require_tail_file = __commonJS({
   "../../node_modules/winston/lib/winston/tail-file.js"(exports2, module2) {
     "use strict";
-    var fs32 = require("fs");
+    var fs33 = require("fs");
     var { StringDecoder } = require("string_decoder");
     var { Stream } = require_readable();
     function noop() {
@@ -8418,7 +8418,7 @@ var require_tail_file = __commonJS({
         stream.emit("end");
         stream.emit("close");
       };
-      fs32.open(options.file, "a+", "0644", (err2, fd) => {
+      fs33.open(options.file, "a+", "0644", (err2, fd) => {
         if (err2) {
           if (!iter) {
             stream.emit("error", err2);
@@ -8430,10 +8430,10 @@ var require_tail_file = __commonJS({
         }
         (function read() {
           if (stream.destroyed) {
-            fs32.close(fd, noop);
+            fs33.close(fd, noop);
             return;
           }
-          return fs32.read(fd, buffer, 0, buffer.length, pos, (error, bytes) => {
+          return fs33.read(fd, buffer, 0, buffer.length, pos, (error, bytes) => {
             if (error) {
               if (!iter) {
                 stream.emit("error", error);
@@ -8492,8 +8492,8 @@ var require_tail_file = __commonJS({
 var require_file = __commonJS({
   "../../node_modules/winston/lib/winston/transports/file.js"(exports2, module2) {
     "use strict";
-    var fs32 = require("fs");
-    var path29 = require("path");
+    var fs33 = require("fs");
+    var path30 = require("path");
     var asyncSeries = require_series();
     var zlib3 = require("zlib");
     var { MESSAGE } = require_triple_beam();
@@ -8523,14 +8523,14 @@ var require_file = __commonJS({
         this._onError = this._onError.bind(this);
         if (options.filename || options.dirname) {
           throwIf("filename or dirname", "stream");
-          this._basename = this.filename = options.filename ? path29.basename(options.filename) : "winston.log";
-          this.dirname = options.dirname || path29.dirname(options.filename);
+          this._basename = this.filename = options.filename ? path30.basename(options.filename) : "winston.log";
+          this.dirname = options.dirname || path30.dirname(options.filename);
           this.options = options.options || { flags: "a" };
         } else if (options.stream) {
           console.warn("options.stream will be removed in winston@4. Use winston.transports.Stream");
           throwIf("stream", "filename", "maxsize");
           this._dest = this._stream.pipe(this._setupStream(options.stream));
-          this.dirname = path29.dirname(this._dest.path);
+          this.dirname = path30.dirname(this._dest.path);
         } else {
           throw new Error("Cannot log to file without filename or stream.");
         }
@@ -8693,11 +8693,11 @@ var require_file = __commonJS({
           options = {};
         }
         options = normalizeQuery(options);
-        const file = path29.join(this.dirname, this.filename);
+        const file = path30.join(this.dirname, this.filename);
         let buff = "";
         let results = [];
         let row = 0;
-        const stream = fs32.createReadStream(file, {
+        const stream = fs33.createReadStream(file, {
           encoding: "utf8"
         });
         stream.on("error", (err2) => {
@@ -8798,7 +8798,7 @@ var require_file = __commonJS({
        * TODO: Refactor me.
        */
       stream(options = {}) {
-        const file = path29.join(this.dirname, this.filename);
+        const file = path30.join(this.dirname, this.filename);
         const stream = new Stream();
         const tail = {
           file,
@@ -8848,8 +8848,8 @@ var require_file = __commonJS({
        */
       stat(callback) {
         const target = this._getFile();
-        const fullpath = path29.join(this.dirname, target);
-        fs32.stat(fullpath, (err2, stat) => {
+        const fullpath = path30.join(this.dirname, target);
+        fs33.stat(fullpath, (err2, stat) => {
           if (err2 && err2.code === "ENOENT") {
             debug("ENOENT\xA0ok", fullpath);
             this.filename = target;
@@ -8952,9 +8952,9 @@ var require_file = __commonJS({
        * @returns {WritableStream} Stream that writes to disk for the active file.
        */
       _createStream(source) {
-        const fullpath = path29.join(this.dirname, this.filename);
+        const fullpath = path30.join(this.dirname, this.filename);
         debug("create stream start", fullpath, this.options);
-        const dest = fs32.createWriteStream(fullpath, this.options).on("error", (err2) => debug(err2)).on("close", () => debug("close", dest.path, dest.bytesWritten)).on("open", () => {
+        const dest = fs33.createWriteStream(fullpath, this.options).on("error", (err2) => debug(err2)).on("close", () => debug("close", dest.path, dest.bytesWritten)).on("open", () => {
           debug("file open ok", fullpath);
           this.emit("open", fullpath);
           source.pipe(dest);
@@ -8977,16 +8977,16 @@ var require_file = __commonJS({
        */
       _incFile(callback) {
         debug("_incFile", this.filename);
-        const ext = path29.extname(this._basename);
-        const basename = path29.basename(this._basename, ext);
+        const ext = path30.extname(this._basename);
+        const basename = path30.basename(this._basename, ext);
         const tasks = [];
         if (this.zippedArchive) {
           tasks.push(
             function(cb) {
               const num = this._created > 0 && !this.tailable ? this._created : "";
               this._compressFile(
-                path29.join(this.dirname, `${basename}${num}${ext}`),
-                path29.join(this.dirname, `${basename}${num}${ext}.gz`),
+                path30.join(this.dirname, `${basename}${num}${ext}`),
+                path30.join(this.dirname, `${basename}${num}${ext}.gz`),
                 cb
               );
             }.bind(this)
@@ -9011,8 +9011,8 @@ var require_file = __commonJS({
        * @private
        */
       _getFile() {
-        const ext = path29.extname(this._basename);
-        const basename = path29.basename(this._basename, ext);
+        const ext = path30.extname(this._basename);
+        const basename = path30.basename(this._basename, ext);
         const isRotation = this.rotationFormat ? this.rotationFormat() : this._created;
         return !this.tailable && this._created ? `${basename}${isRotation}${ext}` : `${basename}${ext}`;
       }
@@ -9032,8 +9032,8 @@ var require_file = __commonJS({
         const isOldest = oldest !== 0 ? oldest : "";
         const isZipped = this.zippedArchive ? ".gz" : "";
         const filePath = `${basename}${isOldest}${ext}${isZipped}`;
-        const target = path29.join(this.dirname, filePath);
-        fs32.unlink(target, callback);
+        const target = path30.join(this.dirname, filePath);
+        fs33.unlink(target, callback);
       }
       /**
        * Roll files forward based on integer, up to maxFiles. e.g. if base if
@@ -9055,20 +9055,20 @@ var require_file = __commonJS({
         for (let x2 = this.maxFiles - 1; x2 > 1; x2--) {
           tasks.push(function(i6, cb) {
             let fileName = `${basename}${i6 - 1}${ext}${isZipped}`;
-            const tmppath = path29.join(this.dirname, fileName);
-            fs32.exists(tmppath, (exists) => {
+            const tmppath = path30.join(this.dirname, fileName);
+            fs33.exists(tmppath, (exists) => {
               if (!exists) {
                 return cb(null);
               }
               fileName = `${basename}${i6}${ext}${isZipped}`;
-              fs32.rename(tmppath, path29.join(this.dirname, fileName), cb);
+              fs33.rename(tmppath, path30.join(this.dirname, fileName), cb);
             });
           }.bind(this, x2));
         }
         asyncSeries(tasks, () => {
-          fs32.rename(
-            path29.join(this.dirname, `${basename}${ext}${isZipped}`),
-            path29.join(this.dirname, `${basename}1${ext}${isZipped}`),
+          fs33.rename(
+            path30.join(this.dirname, `${basename}${ext}${isZipped}`),
+            path30.join(this.dirname, `${basename}1${ext}${isZipped}`),
             callback
           );
         });
@@ -9082,22 +9082,22 @@ var require_file = __commonJS({
        * @private
        */
       _compressFile(src, dest, callback) {
-        fs32.access(src, fs32.F_OK, (err2) => {
+        fs33.access(src, fs33.F_OK, (err2) => {
           if (err2) {
             return callback();
           }
           var gzip = zlib3.createGzip();
-          var inp = fs32.createReadStream(src);
-          var out = fs32.createWriteStream(dest);
+          var inp = fs33.createReadStream(src);
+          var out = fs33.createWriteStream(dest);
           out.on("finish", () => {
-            fs32.unlink(src, callback);
+            fs33.unlink(src, callback);
           });
           inp.pipe(gzip).pipe(out);
         });
       }
       _createLogDirIfNotExist(dirPath) {
-        if (!fs32.existsSync(dirPath)) {
-          fs32.mkdirSync(dirPath, { recursive: true });
+        if (!fs33.existsSync(dirPath)) {
+          fs33.mkdirSync(dirPath, { recursive: true });
         }
       }
     };
@@ -9181,9 +9181,9 @@ var require_http = __commonJS({
         };
         const auth = options.params.auth || null;
         delete options.params.auth;
-        const path29 = options.params.path || null;
+        const path30 = options.params.path || null;
         delete options.params.path;
-        this._request(options, auth, path29, (err2, res, body) => {
+        this._request(options, auth, path30, (err2, res, body) => {
           if (res && res.statusCode !== 200) {
             err2 = new Error(`Invalid HTTP Status Code: ${res.statusCode}`);
           }
@@ -9211,12 +9211,12 @@ var require_http = __commonJS({
           method: "stream",
           params: options
         };
-        const path29 = options.params.path || null;
+        const path30 = options.params.path || null;
         delete options.params.path;
         const auth = options.params.auth || null;
         delete options.params.auth;
         let buff = "";
-        const req = this._request(options, auth, path29);
+        const req = this._request(options, auth, path30);
         stream.destroy = () => req.destroy();
         req.on("data", (data) => {
           data = (buff + data).split(/\n+/);
@@ -9242,14 +9242,14 @@ var require_http = __commonJS({
        * @param {string} path - request path
        * @param {function} callback - Continuation to respond to when complete.
        */
-      _request(options, auth, path29, callback) {
+      _request(options, auth, path30, callback) {
         options = options || {};
         auth = auth || this.auth;
-        path29 = path29 || this.path || "";
+        path30 = path30 || this.path || "";
         if (this.batch) {
-          this._doBatch(options, callback, auth, path29);
+          this._doBatch(options, callback, auth, path30);
         } else {
-          this._doRequest(options, callback, auth, path29);
+          this._doRequest(options, callback, auth, path30);
         }
       }
       /**
@@ -9259,18 +9259,18 @@ var require_http = __commonJS({
        * @param {Object?} auth - authentication options
        * @param {string} path - request path
        */
-      _doBatch(options, callback, auth, path29) {
+      _doBatch(options, callback, auth, path30) {
         this.batchOptions.push(options);
         if (this.batchOptions.length === 1) {
           const me3 = this;
           this.batchCallback = callback;
           this.batchTimeoutID = setTimeout(function() {
             me3.batchTimeoutID = -1;
-            me3._doBatchRequest(me3.batchCallback, auth, path29);
+            me3._doBatchRequest(me3.batchCallback, auth, path30);
           }, this.batchInterval);
         }
         if (this.batchOptions.length === this.batchCount) {
-          this._doBatchRequest(this.batchCallback, auth, path29);
+          this._doBatchRequest(this.batchCallback, auth, path30);
         }
       }
       /**
@@ -9279,14 +9279,14 @@ var require_http = __commonJS({
        * @param {Object?} auth - authentication options
        * @param {string} path - request path
        */
-      _doBatchRequest(callback, auth, path29) {
+      _doBatchRequest(callback, auth, path30) {
         if (this.batchTimeoutID > 0) {
           clearTimeout(this.batchTimeoutID);
           this.batchTimeoutID = -1;
         }
         const batchOptionsCopy = this.batchOptions.slice();
         this.batchOptions = [];
-        this._doRequest(batchOptionsCopy, callback, auth, path29);
+        this._doRequest(batchOptionsCopy, callback, auth, path30);
       }
       /**
        * Make a request to a winstond server or any http server which can
@@ -9296,7 +9296,7 @@ var require_http = __commonJS({
        * @param {Object?} auth - authentication options
        * @param {string} path - request path
        */
-      _doRequest(options, callback, auth, path29) {
+      _doRequest(options, callback, auth, path30) {
         const headers = Object.assign({}, this.headers);
         if (auth && auth.bearer) {
           headers.Authorization = `Bearer ${auth.bearer}`;
@@ -9306,7 +9306,7 @@ var require_http = __commonJS({
           method: "POST",
           host: this.host,
           port: this.port,
-          path: `/${path29.replace(/^\//, "")}`,
+          path: `/${path30.replace(/^\//, "")}`,
           headers,
           auth: auth && auth.username && auth.password ? `${auth.username}:${auth.password}` : "",
           agent: this.agent
@@ -11527,7 +11527,7 @@ var CONSTANTS, Constants_default;
 var init_Constants = __esm({
   "../../packages/constants/src/Constants.ts"() {
     CONSTANTS = {
-      cliVersion: "2.0.1",
+      cliVersion: "2.0.3",
       backendVersion: 1,
       backendPort: 5088,
       workerVersion: 2,
@@ -11584,7 +11584,12 @@ var init_Constants = __esm({
          * whole run, so the entire work list is submitted at once and needs an upper bound. A queued
          * task holds references, not copies, so this bounds the work list rather than memory.
          */
-        MAX_WORKER_QUEUE_SIZE: 1e5
+        MAX_WORKER_QUEUE_SIZE: 1e5,
+        /**
+         * Rows a sample may ask for out of the pipeline. A sample is a look at the data, never an
+         * export of it — `remora sample -s` and the preview's Data tab are both held to this.
+         */
+        MAX_SAMPLE_ROWS: 100
       }
     };
     Constants_default = CONSTANTS;
@@ -12733,7 +12738,7 @@ var init_Validator = __esm({
          */
         this.detectOnFinishRecursion = (consumer) => {
           const errors = [];
-          const path29 = [];
+          const path30 = [];
           const targetsOf = (cons) => {
             const names = [];
             for (const output of cons.outputs ?? []) {
@@ -12745,17 +12750,17 @@ var init_Validator = __esm({
             return names;
           };
           const walk = (name) => {
-            if (path29.some((x2) => x2.toLowerCase() === name.toLowerCase())) {
-              errors.push(`Consumer "${consumer.name}" has a cyclic run-consumer (onSuccess/onError) chain: ${[...path29, name].join(" -> ")}`);
+            if (path30.some((x2) => x2.toLowerCase() === name.toLowerCase())) {
+              errors.push(`Consumer "${consumer.name}" has a cyclic run-consumer (onSuccess/onError) chain: ${[...path30, name].join(" -> ")}`);
               return true;
             }
             const cons = Environment_default.getConsumer(name);
             if (!cons) return false;
-            path29.push(name);
+            path30.push(name);
             for (const target of targetsOf(cons)) {
               if (walk(target)) return true;
             }
-            path29.pop();
+            path30.pop();
             return false;
           };
           walk(consumer.name);
@@ -14241,8 +14246,8 @@ var init_HttpClient = __esm({
             throw new Error(err2.message ?? "An error occurred on GET.");
           }
         };
-        this.getWorkerUrl = (path29) => {
-          const cleanPath = path29.startsWith("/") ? path29.substring(1) : path29;
+        this.getWorkerUrl = (path30) => {
+          const cleanPath = path30.startsWith("/") ? path30.substring(1) : path30;
           return `${this.workerHost}/${cleanPath}`;
         };
         this.workerHost = ProcessENVManager_default.getEnvVariable("REMORA_WORKER_HOST") || "http://worker:5069";
@@ -14685,14 +14690,14 @@ var init_readFile = __esm({
     import_promises3 = require("fs/promises");
     filePromises = {};
     fileIntercept = {};
-    readFile2 = (path29, options) => {
-      if (fileIntercept[path29] !== void 0) {
-        return fileIntercept[path29];
+    readFile2 = (path30, options) => {
+      if (fileIntercept[path30] !== void 0) {
+        return fileIntercept[path30];
       }
-      if (!filePromises[path29] || options?.ignoreCache) {
-        filePromises[path29] = (0, import_promises3.readFile)(path29, "utf8");
+      if (!filePromises[path30] || options?.ignoreCache) {
+        filePromises[path30] = (0, import_promises3.readFile)(path30, "utf8");
       }
-      return filePromises[path29];
+      return filePromises[path30];
     };
   }
 });
@@ -14804,8 +14809,8 @@ var init_externalDataInterceptor = __esm({
       getFileRecord() {
         return fileIntercept;
       },
-      interceptFile(path29, contents) {
-        fileIntercept[path29] = Promise.resolve(contents);
+      interceptFile(path30, contents) {
+        fileIntercept[path30] = Promise.resolve(contents);
       },
       getTokenRecord() {
         return tokenIntercept;
@@ -17885,8 +17890,8 @@ var init_createConfigValueProvider = __esm({
               return endpoint.url.href;
             }
             if ("hostname" in endpoint) {
-              const { protocol, hostname, port, path: path29 } = endpoint;
-              return `${protocol}//${hostname}${port ? ":" + port : ""}${path29}`;
+              const { protocol, hostname, port, path: path30 } = endpoint;
+              return `${protocol}//${hostname}${port ? ":" + port : ""}${path30}`;
             }
           }
           return endpoint;
@@ -18261,18 +18266,18 @@ var getAttrPathList;
 var init_getAttrPathList = __esm({
   "../../node_modules/@smithy/core/dist-es/submodules/endpoints/util-endpoints/lib/getAttrPathList.js"() {
     init_types2();
-    getAttrPathList = (path29) => {
-      const parts = path29.split(".");
+    getAttrPathList = (path30) => {
+      const parts = path30.split(".");
       const pathList = [];
       for (const part of parts) {
         const squareBracketIndex = part.indexOf("[");
         if (squareBracketIndex !== -1) {
           if (part.indexOf("]") !== part.length - 1) {
-            throw new EndpointError(`Path: '${path29}' does not end with ']'`);
+            throw new EndpointError(`Path: '${path30}' does not end with ']'`);
           }
           const arrayIndex = part.slice(squareBracketIndex + 1, -1);
           if (Number.isNaN(parseInt(arrayIndex))) {
-            throw new EndpointError(`Invalid array index: '${arrayIndex}' in path: '${path29}'`);
+            throw new EndpointError(`Invalid array index: '${arrayIndex}' in path: '${path30}'`);
           }
           if (squareBracketIndex !== 0) {
             pathList.push(part.slice(0, squareBracketIndex));
@@ -18293,9 +18298,9 @@ var init_getAttr = __esm({
   "../../node_modules/@smithy/core/dist-es/submodules/endpoints/util-endpoints/lib/getAttr.js"() {
     init_types2();
     init_getAttrPathList();
-    getAttr = (value, path29) => getAttrPathList(path29).reduce((acc, index) => {
+    getAttr = (value, path30) => getAttrPathList(path30).reduce((acc, index) => {
       if (typeof acc !== "object") {
-        throw new EndpointError(`Index '${index}' in '${path29}' not found in '${JSON.stringify(value)}'`);
+        throw new EndpointError(`Index '${index}' in '${path30}' not found in '${JSON.stringify(value)}'`);
       } else if (Array.isArray(acc)) {
         const i6 = parseInt(index);
         return acc[i6 < 0 ? acc.length + i6 : i6];
@@ -18356,8 +18361,8 @@ var init_parseURL = __esm({
             return value;
           }
           if (typeof value === "object" && "hostname" in value) {
-            const { hostname: hostname2, port, protocol: protocol2 = "", path: path29 = "", query = {} } = value;
-            const url = new URL(`${protocol2}//${hostname2}${port ? `:${port}` : ""}${path29}`);
+            const { hostname: hostname2, port, protocol: protocol2 = "", path: path30 = "", query = {} } = value;
+            const url = new URL(`${protocol2}//${hostname2}${port ? `:${port}` : ""}${path30}`);
             url.search = Object.entries(query).map(([k7, v3]) => `${k7}=${v3}`).join("&");
             return url;
           }
@@ -20701,11 +20706,11 @@ var init_HttpBindingProtocol = __esm({
           const opTraits = translateTraits(operationSchema.traits);
           if (opTraits.http) {
             request.method = opTraits.http[0];
-            const [path29, search] = opTraits.http[1].split("?");
+            const [path30, search] = opTraits.http[1].split("?");
             if (request.path == "/") {
-              request.path = path29;
+              request.path = path30;
             } else {
-              request.path += path29;
+              request.path += path30;
             }
             const traitSearchParams = new URLSearchParams(search ?? "");
             for (const [key, value] of traitSearchParams) {
@@ -24418,12 +24423,12 @@ or increase socketAcquisitionWarningTimeout=(millis) in the NodeHttpHandler conf
             const password = request.password ?? "";
             auth = `${username}:${password}`;
           }
-          let path29 = request.path;
+          let path30 = request.path;
           if (queryString) {
-            path29 += `?${queryString}`;
+            path30 += `?${queryString}`;
           }
           if (request.fragment) {
-            path29 += `#${request.fragment}`;
+            path30 += `#${request.fragment}`;
           }
           let hostname = request.hostname ?? "";
           if (hostname[0] === "[" && hostname.endsWith("]")) {
@@ -24435,7 +24440,7 @@ or increase socketAcquisitionWarningTimeout=(millis) in the NodeHttpHandler conf
             headers: request.headers,
             host: hostname,
             method: request.method,
-            path: path29,
+            path: path30,
             port: request.port,
             agent,
             auth
@@ -25344,10 +25349,10 @@ ${longDate}
 ${credentialScope}
 ${toHex(hashedRequest)}`;
       }
-      getCanonicalPath({ path: path29 }) {
+      getCanonicalPath({ path: path30 }) {
         if (this.uriEscapePath) {
           const normalizedPathSegments = [];
-          for (const pathSegment of path29.split("/")) {
+          for (const pathSegment of path30.split("/")) {
             if (pathSegment?.length === 0)
               continue;
             if (pathSegment === ".")
@@ -25358,11 +25363,11 @@ ${toHex(hashedRequest)}`;
               normalizedPathSegments.push(pathSegment);
             }
           }
-          const normalizedPath = `${path29?.startsWith("/") ? "/" : ""}${normalizedPathSegments.join("/")}${normalizedPathSegments.length > 0 && path29?.endsWith("/") ? "/" : ""}`;
+          const normalizedPath = `${path30?.startsWith("/") ? "/" : ""}${normalizedPathSegments.join("/")}${normalizedPathSegments.length > 0 && path30?.endsWith("/") ? "/" : ""}`;
           const doubleEncoded = escapeUri(normalizedPath);
           return doubleEncoded.replace(/%2F/g, "/");
         }
-        return path29;
+        return path30;
       }
       validateResolvedCredentials(credentials) {
         if (typeof credentials !== "object" || typeof credentials.accessKeyId !== "string" || typeof credentials.secretAccessKey !== "string") {
@@ -42569,32 +42574,32 @@ var init_DriverHelper = __esm({
       },
       quickReadFile: async (filePath, lineCount) => {
         const fileStream = (0, import_fs9.createReadStream)(filePath);
-        const rl6 = (0, import_readline.createInterface)({ input: fileStream, crlfDelay: Infinity });
+        const rl7 = (0, import_readline.createInterface)({ input: fileStream, crlfDelay: Infinity });
         const lines = [];
         let counter = 0;
-        for await (const line of rl6) {
+        for await (const line of rl7) {
           lines.push(line);
           counter++;
           if (counter >= lineCount) {
             break;
           }
         }
-        rl6.close();
+        rl7.close();
         fileStream.close();
         return lines;
       },
       quickReadStream: async (stream, lineCount) => {
-        const rl6 = (0, import_readline.createInterface)({ input: stream, crlfDelay: Infinity });
+        const rl7 = (0, import_readline.createInterface)({ input: stream, crlfDelay: Infinity });
         const lines = [];
         let counter = 0;
-        for await (const line of rl6) {
+        for await (const line of rl7) {
           lines.push(line);
           counter++;
           if (counter >= lineCount) {
             break;
           }
         }
-        rl6.close();
+        rl7.close();
         return lines;
       }
     };
@@ -43368,7 +43373,7 @@ var init_S3DestinationDriver = __esm({
 });
 
 // ../../packages/drivers/src/DriverFactory.ts
-var DriverFactoryClass, DriverFactory, DriverFactory_default;
+var STAGEABLE_ENGINES, DriverFactoryClass, DriverFactory, DriverFactory_default;
 var init_DriverFactory = __esm({
   "../../packages/drivers/src/DriverFactory.ts"() {
     init_RedshiftDriver();
@@ -43378,8 +43383,11 @@ var init_DriverFactory = __esm({
     init_LocalDestinationDriver();
     init_S3SourceDriver();
     init_S3DestinationDriver();
+    STAGEABLE_ENGINES = ["local", "aws-s3", "delta-share"];
     DriverFactoryClass = class {
       constructor() {
+        /** Whether a run can stage a producer from this engine — see `STAGEABLE_ENGINES`. */
+        this.canStage = (engine) => STAGEABLE_ENGINES.includes(engine);
         this.instantiateSource = async (source) => {
           switch (source.engine) {
             case "aws-redshift": {
@@ -44132,6 +44140,7 @@ var init_ProducerManager = __esm({
     init_src4();
     init_src3();
     init_src6();
+    init_CryptoEngine();
     ProducerManagerClass = class {
       constructor() {
         this.getColumns = (producer) => {
@@ -44186,6 +44195,46 @@ var init_ProducerManager = __esm({
             return true;
           return FixedWidthParser_default.matchesSelector(line, resolved.selector, resolved.range);
         };
+        /**
+         * The post-parse work a producer implies for every record it produces: which keys carry the
+         * source file name, and which carry a mask.
+         *
+         * Resolved once per chunk, never per line — `getMask` resolves a secret and validates the value,
+         * and neither depends on the record. Empty for almost every producer, which is the case worth
+         * keeping fast.
+         */
+        this.compileFills = (dimensions) => {
+          Affirm_default(dimensions, "Invalid producer dimensions");
+          const fills = [];
+          for (const dimension of dimensions) {
+            const { prodDimension } = dimension;
+            const mask = this.getMask(prodDimension);
+            const sourceFilename = prodDimension.sourceFilename === true;
+            if (!sourceFilename && !Algo_default.hasVal(mask))
+              continue;
+            fills.push({ key: dimension.name, mask, sourceFilename, type: prodDimension.type });
+          }
+          return fills;
+        };
+        /**
+         * Applies the compiled fills to one parsed record, in place.
+         *
+         * The one place a producer dimension's mask is ever applied, on purpose: a run reaches it through
+         * `ProducerExecutor.processLine` and a sample through `ProducerEngine`, and a masked dimension
+         * that came back in the clear from one of the two would be a `hash` the project declared and the
+         * screen ignored — a disclosure, not a display bug.
+         */
+        this.applyFills = (record, fills, sourceFilename) => {
+          if (!fills?.length)
+            return record;
+          for (const fill2 of fills) {
+            if (fill2.sourceFilename)
+              record[fill2.key] = sourceFilename;
+            if (Algo_default.hasVal(fill2.mask))
+              record[fill2.key] = CryptoEngine_default.hashValue(fill2.mask, record[fill2.key]?.toString(), fill2.type);
+          }
+          return record;
+        };
       }
     };
     ProducerManager = new ProducerManagerClass();
@@ -44600,7 +44649,8 @@ var init_ProducerEngine = __esm({
                     }
                   };
                 }
-                const fileData = await this.readFile(effectiveProducer, { readmode: "lines", lines: { from: 0, to: sampleSize } }, effectiveSource);
+                const headerLines = ParseHelper_default.hasHeaderLine(effectiveProducer.settings.fileType, effectiveProducer.settings.hasHeaderRow) ? 1 : 0;
+                const fileData = await this.readFile(effectiveProducer, { readmode: "lines", lines: { from: 0, to: sampleSize + headerLines } }, effectiveSource);
                 rawData = fileData.data;
               } finally {
                 if (scope)
@@ -44619,13 +44669,15 @@ var init_ProducerEngine = __esm({
           if (!rawData || rawData.length === 0) return [];
           const firstItem = rawData[0];
           const isLineData = typeof firstItem === "string";
+          const fills = discover2 ? [] : ProducerManager_default.compileFills(this._fillDimensions(producer));
+          const sourceFilename = import_path18.default.basename(producer.settings.fileKey ?? producer.settings.sqlTable ?? "");
           if (isLineData) {
             const lines = rawData;
             const dimensions = this.deriveDimensions(lines[0], producer, discover2);
             const { fileType, hasHeaderRow } = producer.settings;
             const dataLines = ParseHelper_default.hasHeaderLine(fileType, hasHeaderRow) ? lines.slice(1) : lines;
             const recordSelector = ProducerManager_default.resolveRecordSelector(producer);
-            return dataLines.filter((line) => line.trim().length > 0).filter((line) => ProducerManager_default.shouldReadLine(line, recordSelector)).flatMap((line) => LineParser_default.parseAll(line, producer, dimensions, noopTracker));
+            return dataLines.filter((line) => line.trim().length > 0).filter((line) => ProducerManager_default.shouldReadLine(line, recordSelector)).flatMap((line) => LineParser_default.parseAll(line, producer, dimensions, noopTracker)).map((record) => ProducerManager_default.applyFills(record, fills, sourceFilename));
           }
           if (discover2) {
             return rawData.map((item) => ({ ...item }));
@@ -44636,9 +44688,15 @@ var init_ProducerEngine = __esm({
               const key = dim.alias ?? dim.name;
               record[dim.name] = TypeCaster_default.cast(item[key], dim.type, dim.format);
             }
-            return record;
+            return ProducerManager_default.applyFills(record, fills, sourceFilename);
           });
         };
+        /**
+         * The producer's declared dimensions in the shape `compileFills` reads them in. Declaration
+         * order, because a fill is addressed by key and never by position — unlike the executor
+         * dimensions of a run, whose index is reconciled against the file's own header.
+         */
+        this._fillDimensions = (producer) => producer.dimensions.map((prodDimension, index) => ({ index, name: prodDimension.name, prodDimension }));
         /**
          * Builds the executor dimensions of a producer. There are two shapes of source: a FIXED file has
          * no header, so its layout comes from the positions declared on the dimensions; every other file
@@ -47106,9 +47164,10 @@ var init_MockDataFactory = __esm({
           if (type === "number") {
             const first = bounds?.min ?? 1;
             const last = first + poolSize - 1;
+            const ceiling = bounds?.max;
             Affirm_default(
-              bounds?.max === void 0 || bounds.max >= last,
-              `Key "${norm}" has a synth range of ${first}-${bounds.max}, which holds fewer than the ${poolSize} distinct values it has to generate; widen it or generate fewer records`
+              ceiling === void 0 || ceiling >= last,
+              `Key "${norm}" has a synth range of ${first}-${ceiling}, which holds fewer than the ${poolSize} distinct values it has to generate; widen it or generate fewer records`
             );
             for (let i6 = 0; i6 < poolSize; i6++) pool.push(first + i6);
             return pool;
@@ -48449,23 +48508,23 @@ var init_Diagnostics = __esm({
           return [.../* @__PURE__ */ new Set([...inputs, ...chained])];
         };
         this._walk = (start, next, onCycle) => {
-          const path29 = [];
+          const path30 = [];
           const onPath = /* @__PURE__ */ new Set();
           const stack = [{ name: start, done: false }];
           const visited = /* @__PURE__ */ new Set();
           while (stack.length > 0) {
             const frame = stack.pop();
             if (frame.done) {
-              onPath.delete(path29.pop());
+              onPath.delete(path30.pop());
               continue;
             }
             if (onPath.has(frame.name)) {
-              path29.slice(path29.indexOf(frame.name)).forEach((name) => onCycle.add(name));
+              path30.slice(path30.indexOf(frame.name)).forEach((name) => onCycle.add(name));
               continue;
             }
             if (visited.has(frame.name)) continue;
             visited.add(frame.name);
-            path29.push(frame.name);
+            path30.push(frame.name);
             onPath.add(frame.name);
             stack.push({ name: frame.name, done: true });
             const successors = next.get(frame.name) ?? [];
@@ -49143,8 +49202,8 @@ var init_ResourceView = __esm({
           if (!source || origin.path.length < 2) return { value: "declared here", muted: true };
           return { value: `${source.resource}.${source.field}`, link: source.node };
         };
-        this._pathText = (path29) => {
-          return path29.map((step) => `${step.resource}.${step.field}`).join(" \u2192 ");
+        this._pathText = (path30) => {
+          return path30.map((step) => `${step.resource}.${step.field}`).join(" \u2192 ");
         };
         this._consumerOutputsTable = (env2, consumer) => {
           const declared = new Set((env2.sources ?? []).map((x2) => x2.name));
@@ -49886,17 +49945,30 @@ var init_LocalUsageDB = __esm({
           }
         };
         /**
-         * The recorded runs, newest first. Only the tail of the file is decoded: a reader wants the recent
+         * The recorded runs, newest first — the newest `limit` of the rows `keep` accepts.
+         *
+         * Decoded from the end and stopped as soon as that many are held: a reader wants the recent
          * executions, and decoding ten thousand rows to show ten of them is work nobody asked for.
          *
+         * `keep` is applied BEFORE the limit, which is the only way "the newest N runs of this kind" can
+         * mean it: filtering afterwards lets the rows a caller does not want displace the ones it does,
+         * so one sample recorded here would silently push a real run out of a history someone is reading.
+         *
          * Never throws. A missing file reads as no history, and so does a half-written one — this store is
          * appended to while it is being read, so failing on that would make it unreadable during a run.
          */
-        this.list = (limit = MAX_LISTED_ROWS) => {
+        this.list = (limit = MAX_LISTED_ROWS, keep) => {
           try {
             if (!(0, import_fs16.existsSync)(CLI_DB_PATH))
               return [];
-            return this._getRows().slice(-Math.max(1, limit)).map((line) => this._fromLine(line)).reverse();
+            const rows = this._getRows();
+            const wanted = Math.max(1, limit);
+            const found = [];
+            for (let index = rows.length - 1; index >= 0 && found.length < wanted; index--) {
+              const usage = this._fromLine(rows[index]);
+              if (!keep || keep(usage)) found.push(usage);
+            }
+            return found;
           } catch (error) {
             this._handleError("list", error);
             return [];
@@ -50077,9 +50149,10 @@ var init_UsageManager = __esm({
 });
 
 // ../../packages/engines/src/ops/RunOverlay.ts
-var MAX_RUNS, MAX_OPERATIONS, RunOverlayClass, RunOverlay, RunOverlay_default;
+var import_crypto5, MAX_RUNS, MAX_OPERATIONS, RunOverlayClass, RunOverlay, RunOverlay_default;
 var init_RunOverlay = __esm({
   "../../packages/engines/src/ops/RunOverlay.ts"() {
+    import_crypto5 = __toESM(require("crypto"), 1);
     init_src();
     init_LineageEngine();
     init_LocalUsageDB();
@@ -50088,6 +50161,8 @@ var init_RunOverlay = __esm({
     MAX_OPERATIONS = 40;
     RunOverlayClass = class {
       constructor() {
+        /** The last store token read, and the overlay token it resolved to. */
+        this._signed = { store: null, overlay: "" };
         /**
          * The recent executions and their aggregates. ONE read of the store answers both, so a page
          * showing a graph, a run list and a timing breakdown costs one file read rather than three.
@@ -50098,20 +50173,40 @@ var init_RunOverlay = __esm({
         this.read = (limit = MAX_RUNS) => {
           Affirm_default(limit > 0, "Run overlay limit must be greater than zero");
           if (!UsageManager_default.recordsLocally()) return { runs: [], metrics: {} };
-          const stats = LocalUsageDB_default.list(limit).filter((stat) => stat?.consumer);
+          const stats = LocalUsageDB_default.list(limit, (stat) => !!stat?.consumer && stat.invokedBy !== "SAMPLE");
           return { runs: stats.map((stat) => this._run(stat)), metrics: this._metrics(stats) };
         };
         /**
-         * A token that changes when the run store does. Empty when there is nothing to read.
+         * A token that changes when the OVERLAY does. Empty when there is nothing to read.
          *
          * A run finishing changes no configuration file, so the config hash cannot notice it — this is
-         * the second half of what the preview polls, and it is cheap for the same reason the hash is
-         * affordable: it reads metadata, not records.
+         * the second half of what the preview polls.
+         *
+         * It signs the painted runs rather than the store, because the two do not move together: a
+         * sample is recorded like any other execution and then filtered out of `read`, so the store's
+         * own token changes while the picture does not. Signing the store there announced a project
+         * change for every sample — and a page told its resource changed drops the sample it is showing,
+         * which is exactly the rows someone had just asked for.
+         *
+         * Still cheap to poll: the store's mtime/size gates the read, so the rows are decoded only after
+         * something has actually been written, never once a second.
          */
         this.signature = () => {
           if (!UsageManager_default.recordsLocally()) return "";
-          return LocalUsageDB_default.signature();
+          const store = LocalUsageDB_default.signature();
+          if (store === this._signed.store) return this._signed.overlay;
+          const overlay = this._token(this.read());
+          this._signed = { store, overlay };
+          return overlay;
         };
+        /**
+         * A token over the whole overlay, runs and metrics alike.
+         *
+         * Everything it carries, not the newest row and a count: `endUsage` updates a row in place and a
+         * finish action writes runs of its own, so a narrower token would miss a transition the graph
+         * exists to show.
+         */
+        this._token = (overlay) => import_crypto5.default.createHash("sha256").update(JSON.stringify(overlay)).digest("hex");
         this._run = (stat) => {
           const startedAt = this._iso(stat.startedAt);
           return {
@@ -50358,64 +50453,6 @@ var init_PushdownEngine = __esm({
   }
 });
 
-// ../../packages/engines/src/producer/SampleEngine.ts
-var MAX_CHAIN_DEPTH2, SampleEngineClass, SampleEngine, SampleEngine_default;
-var init_SampleEngine = __esm({
-  "../../packages/engines/src/producer/SampleEngine.ts"() {
-    init_src();
-    init_src4();
-    init_ProducerEngine();
-    MAX_CHAIN_DEPTH2 = 20;
-    SampleEngineClass = class {
-      constructor() {
-        /**
-         * @param resourceName a producer or consumer name, as declared.
-         * @throws when the name is neither, or when the source cannot be read.
-         */
-        this.read = async (resourceName, size = 10) => {
-          Affirm_default(resourceName, "Missing resource name to sample");
-          Affirm_default(size > 0, "Sample size must be greater than 0");
-          const producer = Environment_default.getProducer(resourceName);
-          if (producer)
-            return { kind: "producer", name: resourceName, records: await ProducerEngine_default.readSampleData(producer, size, false) };
-          const consumer = Environment_default.getConsumer(resourceName);
-          Affirm_default(consumer, `Resource "${resourceName}" not found. Please check if it exists as a producer or consumer.`);
-          return { kind: "consumer", name: resourceName, records: await this._readConsumer(consumer, size, []) };
-        };
-        /**
-         * A consumer has no data of its own until it runs, so what it shows is its FIRST input, projected
-         * through its field list — near enough to answer "what will come out of this" without a run.
-         */
-        this._readConsumer = async (consumer, size, visited) => {
-          Affirm_default(!visited.includes(consumer.name), `Consumer "${consumer.name}" reads itself through ${visited.join(" \u2192 ")}`);
-          Affirm_default(visited.length < MAX_CHAIN_DEPTH2, `Consumer chain from "${visited[0]}" is more than ${MAX_CHAIN_DEPTH2} deep`);
-          const input = consumer.producers[0];
-          Affirm_default(input, `Consumer "${consumer.name}" has no producers configured`);
-          const producer = Environment_default.getProducer(input.name);
-          if (!producer) {
-            const upstream = Environment_default.getConsumer(input.name);
-            Affirm_default(upstream, `Producer or consumer "${input.name}" not found for consumer "${consumer.name}"`);
-            return this._readConsumer(upstream, size, [...visited, consumer.name]);
-          }
-          const records = await ProducerEngine_default.readSampleData(producer, size, false);
-          if (consumer.fields.some((field) => field.key === "*")) return records;
-          return records.map((record) => this._project(consumer, record));
-        };
-        this._project = (consumer, record) => {
-          const projected = {};
-          for (const field of consumer.fields) {
-            if (field.key === "*") continue;
-            projected[field.alias || field.key] = record[field.key];
-          }
-          return projected;
-        };
-      }
-    };
-    SampleEngine = new SampleEngineClass();
-    SampleEngine_default = SampleEngine;
-  }
-});
-
 // ../../packages/engines/src/transform/LookupRegistry.ts
 var LookupRegistryClass, LookupRegistry, LookupRegistry_default;
 var init_LookupRegistry = __esm({
@@ -50452,12 +50489,12 @@ var init_LookupRegistry = __esm({
 });
 
 // ../../packages/engines/src/transform/LookupKey.ts
-var import_crypto5, DELIMITER, idFor, LookupKey, LookupKey_default;
+var import_crypto6, DELIMITER, idFor, LookupKey, LookupKey_default;
 var init_LookupKey = __esm({
   "../../packages/engines/src/transform/LookupKey.ts"() {
-    import_crypto5 = __toESM(require("crypto"), 1);
+    import_crypto6 = __toESM(require("crypto"), 1);
     DELIMITER = String.fromCharCode(0);
-    idFor = (ref) => import_crypto5.default.createHash("sha1").update([ref.consumer, ref.key, ref.value].join(DELIMITER)).digest("hex").slice(0, 16);
+    idFor = (ref) => import_crypto6.default.createHash("sha1").update([ref.consumer, ref.key, ref.value].join(DELIMITER)).digest("hex").slice(0, 16);
     LookupKey = { idFor };
     LookupKey_default = LookupKey;
   }
@@ -51094,7 +51131,6 @@ var init_src10 = __esm({
     init_ProducerEngine();
     init_ProducerManager();
     init_PushdownEngine();
-    init_SampleEngine();
     init_TransformationEngine();
     init_TypeCaster();
     init_LookupRegistry();
@@ -51264,14 +51300,14 @@ var init_OutputExecutor = __esm({
 });
 
 // ../../packages/executors/src/ConsumerExecutor.ts
-var import_path23, import_fs17, import_readline6, import_promises13, import_crypto6, LIMIT_SCAN_BYTES, NEWLINE_BYTE, ConsumerExecutorClass, ConsumerExecutor, ConsumerExecutor_default;
+var import_path23, import_fs17, import_readline6, import_promises13, import_crypto7, LIMIT_SCAN_BYTES, NEWLINE_BYTE, ConsumerExecutorClass, ConsumerExecutor, ConsumerExecutor_default;
 var init_ConsumerExecutor = __esm({
   "../../packages/executors/src/ConsumerExecutor.ts"() {
     import_path23 = __toESM(require("path"));
     import_fs17 = __toESM(require("fs"));
     import_readline6 = __toESM(require("readline"));
     import_promises13 = __toESM(require("fs/promises"));
-    import_crypto6 = __toESM(require("crypto"));
+    import_crypto7 = __toESM(require("crypto"));
     init_src10();
     init_src10();
     init_src10();
@@ -51510,7 +51546,7 @@ var init_ConsumerExecutor = __esm({
           let newLineCount = 0;
           const seen = /* @__PURE__ */ new Set();
           for await (const line of lineReader) {
-            const hash = import_crypto6.default.createHash("sha1").update(line).digest("base64");
+            const hash = import_crypto7.default.createHash("sha1").update(line).digest("base64");
             if (!seen.has(hash)) {
               seen.add(hash);
               if (!writer.write(line + "\n"))
@@ -51786,8 +51822,6 @@ var init_ProducerExecutor = __esm({
     init_src8();
     init_src4();
     init_src10();
-    init_src();
-    init_src10();
     init_src10();
     import_path24 = __toESM(require("path"));
     init_src2();
@@ -51818,20 +51852,14 @@ var init_ProducerExecutor = __esm({
          * the source file name or a mask, and what that file name is. None of it depends on the line, so
          * it is compiled once per chunk instead of rebuilt per line — including the mask's own
          * validation, which used to run once per dimension per line.
+         *
+         * The fills themselves come from `ProducerManager`, which is also where the sample path gets
+         * them: one producer stage, reached from two places.
          */
         this.compileLine = (dimensions, chunk) => {
           Affirm_default(dimensions, "Invalid producer dimensions");
           Affirm_default(chunk, "Invalid chunk");
-          const fills = [];
-          for (const dimension of dimensions) {
-            const { prodDimension } = dimension;
-            const mask = ProducerManager_default.getMask(prodDimension);
-            const sourceFilename = prodDimension.sourceFilename === true;
-            if (!sourceFilename && !Algo_default.hasVal(mask))
-              continue;
-            fills.push({ key: dimension.name, mask, sourceFilename, type: prodDimension.type });
-          }
-          return { fills, sourceFilename: import_path24.default.basename(chunk.fileUri) };
+          return { fills: ProducerManager_default.compileFills(dimensions), sourceFilename: import_path24.default.basename(chunk.fileUri) };
         };
         /**
          * The record(s) one source line produces. Almost always exactly one — a producer with a group
@@ -51852,14 +51880,8 @@ var init_ProducerExecutor = __esm({
           if (plan.fills.length === 0)
             return records;
           counter = performance.now();
-          for (const record of records) {
-            for (const fill2 of plan.fills) {
-              if (fill2.sourceFilename)
-                record[fill2.key] = plan.sourceFilename;
-              if (Algo_default.hasVal(fill2.mask))
-                record[fill2.key] = CryptoEngine_default.hashValue(fill2.mask, record[fill2.key]?.toString(), fill2.type);
-            }
-          }
+          for (const record of records)
+            ProducerManager_default.applyFills(record, plan.fills, plan.sourceFilename);
           tracker.measure("process-line:dimensions-filename-mask", performance.now() - counter);
           return records;
         };
@@ -52627,7 +52649,8 @@ var init_ExecutorOrchestrator = __esm({
           } catch (error) {
             Logger_default.log(`[${usageId}] Consumer "${consumer.name}" failed: ${Helper_default.asError(error).message} | ${OrchestratorHelper_default.formatMemoryUsage()}`);
             Logger_default.error(error);
-            await ConsumerOnFinishManager_default.onConsumerError(consumer, usageId, this.makeOnFinishRunner(consumer, request, usageId));
+            if (!request.skipExport)
+              await ConsumerOnFinishManager_default.onConsumerError(consumer, usageId, this.makeOnFinishRunner(consumer, request, usageId));
             Logger_default.log(`[${usageId}] Running cleanup after failure`);
             await this.performCleanupOperations(scope, tracker);
             UsageManager_default.failUsage(usageId, Helper_default.asError(error).message);
@@ -53826,6 +53849,164 @@ init_src4();
 init_OutputExecutor();
 init_ProducerExecutor();
 
+// ../../packages/executors/src/SampleRunner.ts
+var import_fs21 = __toESM(require("fs"));
+var import_promises18 = __toESM(require("fs/promises"));
+var import_path29 = __toESM(require("path"));
+var import_readline10 = __toESM(require("readline"));
+init_src();
+init_src3();
+init_src4();
+init_src8();
+init_src10();
+init_src5();
+init_src2();
+init_ExecutorOrchestrator();
+var MAX_WALK_DEPTH = 20;
+var SAMPLE_USER = { user: { _id: "sample", name: "sample", type: "licence" } };
+var SampleRunnerClass = class {
+  constructor() {
+    /**
+     * @param resourceName a producer or consumer name, as declared.
+     * @param rows the most rows to return, capped at `MAX_SAMPLE_ROWS`.
+     * @throws when the name is neither, when a source cannot be read, or when the pipeline itself
+     *         fails — a consumer whose transformation throws is a sample that reports the reason.
+     */
+    this.read = async (resourceName, rows = 10, details) => {
+      Affirm_default(resourceName, "Missing resource name to sample");
+      Affirm_default(rows > 0, "Sample size must be greater than 0");
+      const size = Math.min(rows, Constants_default.defaults.MAX_SAMPLE_ROWS);
+      const producer = Environment_default.getProducer(resourceName);
+      if (producer) {
+        const records = await ProducerEngine_default.readSampleData(producer, size, false);
+        return {
+          kind: "producer",
+          name: resourceName,
+          records,
+          note: `${records.length} row(s) read from the source now, with this producer's dimensions, types and masks applied.`
+        };
+      }
+      const consumer = Environment_default.getConsumer(resourceName);
+      Affirm_default(consumer, `Resource "${resourceName}" not found. Please check if it exists as a producer or consumer.`);
+      return this._runConsumer(consumer, size, details);
+    };
+    /**
+     * Runs the consumer for real and reads back what it produced.
+     *
+     * The output is captured instead of exported, so nothing reaches the consumer's destination and
+     * no onSuccess action fires: looking at data must never be indistinguishable from publishing it.
+     */
+    this._runConsumer = async (consumer, size, details) => {
+      this._assertStageable(consumer);
+      const capturePath = import_path29.default.resolve(import_path29.default.join(ExecutorScope_default.getBasePath(), `sample_${consumer.name}_${Helper_default.uuid()}.jsonl`));
+      ExecutorScope_default.ensurePath(capturePath);
+      try {
+        const result = await ExecutorOrchestrator_default.launch({
+          consumer,
+          // `SAMPLE`, so the run it records is distinguishable from one the project did. The
+          // executor treats it like any other invocation; only `RunOverlay` reads the marker.
+          details: { ...details ?? SAMPLE_USER, invokedBy: "SAMPLE" },
+          // The rows asked for, bounded the way `remora run -l` bounds them — pushed to the
+          // source and stopped early per worker wherever nothing downstream can drop a record.
+          options: { limit: size },
+          // Nothing reaches the destination and no finish action fires; the merged dataset
+          // comes back through the same capture the lookup and consumer-input runs use.
+          skipExport: true,
+          captureMainDatasetTo: capturePath,
+          captureFormat: "JSONL"
+        });
+        const captured = await this._readCapture(capturePath, size);
+        const records = captured.map((record) => this._inFieldOrder(consumer, record));
+        Logger_default.log(`[sample] Consumer "${consumer.name}": ${records.length} row(s) from ${result.inputCount} input line(s)`);
+        return {
+          kind: "consumer",
+          name: consumer.name,
+          records,
+          note: `${records.length} row(s) from the real pipeline \u2014 filters, transformations, masking and validation all applied, exactly as in a run. Nothing was written to the destination.`
+        };
+      } finally {
+        await import_promises18.default.rm(capturePath, { force: true });
+      }
+    };
+    /**
+     * Refuses, naming the source, when a run could not read one of this consumer's producers.
+     *
+     * `RedshiftDriver.ready` and `HttpApiSourceDriver.ready` are unimplemented, so the pipeline
+     * cannot reach those sources at all. Checked up front because the alternative is a run that
+     * spins up a worker pool and then surfaces "Not implemented yet" from three layers down, which
+     * names neither the producer nor the source that caused it.
+     */
+    this._assertStageable = (consumer) => {
+      for (const producer of this._inputProducers(consumer)) {
+        const source = Environment_default.getSource(producer.source);
+        Affirm_default(source, `Producer "${producer.name}" of consumer "${consumer.name}" has no source "${producer.source}"`);
+        if (!DriverFactory_default.canStage(source.engine))
+          throw new Error(`Cannot sample consumer "${consumer.name}": its producer "${producer.name}" reads source "${source.name}", and a "${source.engine}" source cannot be run through the pipeline yet. Sample the producer "${producer.name}" instead to see its rows.`);
+      }
+    };
+    /**
+     * Every producer a run of this consumer would stage — its own, plus those of the consumers it
+     * reads as input or consults as a code_lookup table, since each of those is executed too.
+     */
+    this._inputProducers = (consumer, visited = []) => {
+      Affirm_default(!visited.includes(consumer.name), `Consumer "${consumer.name}" reads itself through ${visited.join(" \u2192 ")}`);
+      Affirm_default(visited.length < MAX_WALK_DEPTH, `Consumer chain from "${visited[0]}" is more than ${MAX_WALK_DEPTH} deep`);
+      const seen = [...visited, consumer.name];
+      const upstream = [
+        ...consumer.producers.map((entry) => entry.name),
+        ...ConsumerManager_default.collectLookupRefs(ConsumerManager_default.getExpandedFields(consumer)).map((ref) => ref.consumer)
+      ];
+      return upstream.flatMap((name) => {
+        const producer = Environment_default.getProducer(name);
+        if (producer) return [producer];
+        const nested = Environment_default.getConsumer(name);
+        Affirm_default(nested, `Producer or consumer "${name}" not found for consumer "${consumer.name}"`);
+        return this._inputProducers(nested, seen);
+      });
+    };
+    /**
+     * One row's keys in the order the consumer DECLARES its fields.
+     *
+     * A record comes out of a worker keyed in the order the producer's dimensions were read, which is
+     * the source's layout and not the consumer's — so a consumer declaring country, plan, is_active
+     * over a producer that stores is_active first would be shown its own columns in someone else's
+     * order. Invisible in an exported JSON object; the whole shape of the table here.
+     *
+     * Anything the record carries that the field list does not name is appended rather than dropped:
+     * a column that turns up unexpectedly is exactly the one worth seeing.
+     */
+    this._inFieldOrder = (consumer, record) => {
+      const declared = ConsumerManager_default.getExpandedFields(consumer).filter((field) => !field.cField.hidden).map((field) => field.finalKey);
+      const ordered = {};
+      for (const key of declared) {
+        if (key in record) ordered[key] = record[key];
+      }
+      for (const key of Object.keys(record)) {
+        if (!(key in ordered)) ordered[key] = record[key];
+      }
+      return ordered;
+    };
+    /** The captured dataset, which `captureFormat: 'JSONL'` guarantees is one JSON object per line. */
+    this._readCapture = async (capturePath, size) => {
+      if (!import_fs21.default.existsSync(capturePath)) return [];
+      const records = [];
+      const lines = import_readline10.default.createInterface({ input: import_fs21.default.createReadStream(capturePath), crlfDelay: Infinity });
+      try {
+        for await (const line of lines) {
+          if (!line.length) continue;
+          records.push(JSON.parse(line));
+          if (records.length >= size) break;
+        }
+      } finally {
+        lines.close();
+      }
+      return records;
+    };
+  }
+};
+var SampleRunner = new SampleRunnerClass();
+var SampleRunner_default = SampleRunner;
+
 // src/actions/run.ts
 init_src4();
 init_src2();
@@ -54018,6 +54199,7 @@ init_src5();
 init_src2();
 var WATCH_INTERVAL_MS = 1e3;
 var SAMPLEABLE_KINDS = ["producer", "consumer"];
+var PIPELINE_SAMPLE_KINDS = ["consumer"];
 var EDITABLE_KINDS = {
   source: "source",
   producer: "producer",
@@ -54054,11 +54236,15 @@ var PreviewProject = class {
     this._files = [];
     this._hash = null;
     /**
-     * The consumer a run started from this page is executing, or null.
+     * What this page is currently executing, or null — a run, or a consumer sample.
      *
-     * One at a time, deliberately: `remora run` runs consumers sequentially, and two concurrent runs
-     * would each spin up a worker pool in this one process. Refusing the second with the name of the
-     * first is a better answer than thrashing the machine.
+     * One at a time, deliberately: `remora run` runs consumers sequentially, and two concurrent
+     * executions would each spin up a worker pool in this one process. Refusing the second with the
+     * name of the first is a better answer than thrashing the machine.
+     *
+     * A sample takes the same lock because it IS an execution: bounded at the input and exporting
+     * nothing, but a worker pool either way. That also means a sample and a run cannot overlap, which
+     * is what stops a click on one panel from slowing the run someone is watching on another.
      */
     this._running = null;
     /** @returns true when the project changed and the snapshot was rebuilt. */
@@ -54104,18 +54290,47 @@ var PreviewProject = class {
           ]
         };
       },
-      sample: async (nodeId, rows) => {
-        if (!this._has(nodeId)) return null;
-        const { kind, name } = LineageEngine_default.parseNodeId(nodeId);
-        if (!SAMPLEABLE_KINDS.includes(kind)) return null;
-        const { records } = await SampleEngine_default.read(name, rows);
-        return ResourceView_default.buildSampleTable(records);
-      },
+      sample: async (nodeId, rows) => this._sample(nodeId, rows),
       run: async (nodeId) => this._run(nodeId),
       file: (nodeId) => this._file(nodeId),
       save: async (nodeId, content) => this._save(nodeId, content),
       logs: (lines) => this._logs(lines)
     });
+    /**
+     * The rows a resource actually holds, as a table.
+     *
+     * A producer answers from a bounded read of its source. A consumer answers by RUNNING — every
+     * filter, transformation, mask, union, distinct, pivot and validation it declares, over a
+     * bounded slice of each producer's input, exporting nothing and recording nothing. Which of the
+     * two happened, and over how much input, is the note `SampleRunner` returns; it becomes the
+     * table's title, so the panel states what it is showing instead of leaving it to be assumed.
+     *
+     * Awaited, unlike a run: a sample is bounded, and its ANSWER is the rows — there is nothing for
+     * the run overlay to show, because a sample deliberately leaves no trace on it.
+     */
+    this._sample = async (nodeId, rows) => {
+      if (!this._has(nodeId)) return null;
+      const { kind, name } = LineageEngine_default.parseNodeId(nodeId);
+      if (!SAMPLEABLE_KINDS.includes(kind)) return null;
+      const pipeline5 = PIPELINE_SAMPLE_KINDS.includes(kind);
+      if (pipeline5 && this._running)
+        throw new Error(`"${this._running}" is still running; one execution at a time`);
+      const blocking = pipeline5 ? this.snapshot.diagnostics.find((x2) => x2.node === nodeId && x2.severity === "error") : null;
+      if (blocking) throw new Error(`Refusing to sample "${name}": ${blocking.message}`);
+      if (pipeline5) this._running = name;
+      try {
+        const licence = LicenceManager_default.validate(ProcessENVManager_default.getEnvVariable("REMORA_LICENCE_KEY"));
+        const { records, note } = await SampleRunner_default.read(name, rows, {
+          // A sample from the preview is a sample from the CLI. It records no usage, so this
+          // only ever names the run in the log.
+          invokedBy: "CLI",
+          user: { _id: licence.customer, name: licence.customer, type: "licence" }
+        });
+        return ResourceView_default.buildSampleTable(records, note);
+      } finally {
+        if (pipeline5) this._running = null;
+      }
+    };
     /**
      * Executes a consumer, and answers as soon as it has STARTED.
      *
@@ -54127,7 +54342,7 @@ var PreviewProject = class {
       if (!this._has(nodeId)) return { started: false, message: `No resource "${nodeId}" in this project` };
       const { kind, name } = LineageEngine_default.parseNodeId(nodeId);
       if (kind !== "consumer") return { started: false, message: `Only a consumer can be run; "${name}" is a ${kind}` };
-      if (this._running) return { started: false, message: `"${this._running}" is still running; one run at a time` };
+      if (this._running) return { started: false, message: `"${this._running}" is still running; one execution at a time` };
       const blocking = this.snapshot.diagnostics.find((x2) => x2.node === nodeId && x2.severity === "error");
       if (blocking) return { started: false, message: `Refusing to run "${name}": ${blocking.message}` };
       const consumer = Environment_default.getConsumer(name);
@@ -54251,22 +54466,22 @@ var stopOnSignal = (server, watch) => {
 
 // src/actions/create_producer.ts
 var import_chalk11 = __toESM(require("chalk"));
-var import_fs21 = __toESM(require("fs"));
-var import_path29 = __toESM(require("path"));
+var import_fs22 = __toESM(require("fs"));
+var import_path30 = __toESM(require("path"));
 init_src2();
 var create_producer = async (name) => {
   try {
-    if (!import_fs21.default.existsSync("./remora/producers")) {
+    if (!import_fs22.default.existsSync("./remora/producers")) {
       throw new Error(import_chalk11.default.red("Missing directory: ") + import_chalk11.default.yellow("./remora/producers"));
     }
-    const defaultProducerTemplate = import_fs21.default.readFileSync(
-      import_path29.default.join(DOCUMENTATION_DIR, "default_resources/producer.json"),
+    const defaultProducerTemplate = import_fs22.default.readFileSync(
+      import_path30.default.join(DOCUMENTATION_DIR, "default_resources/producer.json"),
       "utf-8"
     );
     const defaultProducer = JSON.parse(defaultProducerTemplate);
     defaultProducer.name = name;
-    const producerPath = import_path29.default.join("remora/producers", `${name}.json`);
-    import_fs21.default.writeFileSync(producerPath, JSON.stringify(defaultProducer, null, 4));
+    const producerPath = import_path30.default.join("remora/producers", `${name}.json`);
+    import_fs22.default.writeFileSync(producerPath, JSON.stringify(defaultProducer, null, 4));
     console.log(import_chalk11.default.green(`\u2705 Created producer config at ${producerPath}`));
     console.log(import_chalk11.default.blue("Remember to:"));
     console.log(import_chalk11.default.blue("1. Set the correct source name"));
@@ -54281,26 +54496,26 @@ var create_producer = async (name) => {
 
 // src/actions/create_consumer.ts
 var import_chalk12 = __toESM(require("chalk"));
-var import_fs22 = __toESM(require("fs"));
-var import_path30 = __toESM(require("path"));
+var import_fs23 = __toESM(require("fs"));
+var import_path31 = __toESM(require("path"));
 init_src2();
 var create_consumer = async (name, producerName) => {
   try {
-    if (!import_fs22.default.existsSync("./remora/consumers")) {
+    if (!import_fs23.default.existsSync("./remora/consumers")) {
       throw new Error(import_chalk12.default.red("Missing directory: ") + import_chalk12.default.yellow("./remora/consumers"));
     }
-    const defaultConsumerTemplate = import_fs22.default.readFileSync(
-      import_path30.default.join(DOCUMENTATION_DIR, "default_resources/consumer.json"),
+    const defaultConsumerTemplate = import_fs23.default.readFileSync(
+      import_path31.default.join(DOCUMENTATION_DIR, "default_resources/consumer.json"),
       "utf-8"
     );
     const defaultConsumer = JSON.parse(defaultConsumerTemplate);
     defaultConsumer.name = name;
     if (producerName) {
-      const producerPath = import_path30.default.join("remora/producers", `${producerName}.json`);
-      if (!import_fs22.default.existsSync(producerPath)) {
+      const producerPath = import_path31.default.join("remora/producers", `${producerName}.json`);
+      if (!import_fs23.default.existsSync(producerPath)) {
         throw new Error(import_chalk12.default.red("Producer not found: ") + import_chalk12.default.yellow(producerPath));
       }
-      const producerConfig = JSON.parse(import_fs22.default.readFileSync(producerPath, "utf-8"));
+      const producerConfig = JSON.parse(import_fs23.default.readFileSync(producerPath, "utf-8"));
       defaultConsumer.producers = [{ name: producerName }];
       defaultConsumer.fields = producerConfig.dimensions.map((dim) => ({
         key: dim.name,
@@ -54319,8 +54534,8 @@ var create_consumer = async (name, producerName) => {
       defaultConsumer.filters = void 0;
       defaultConsumer.metadata = void 0;
     }
-    const consumerPath = import_path30.default.join("remora/consumers", `${name}.json`);
-    import_fs22.default.writeFileSync(consumerPath, JSON.stringify(defaultConsumer, null, 4));
+    const consumerPath = import_path31.default.join("remora/consumers", `${name}.json`);
+    import_fs23.default.writeFileSync(consumerPath, JSON.stringify(defaultConsumer, null, 4));
     console.log(import_chalk12.default.green(`\u2705 Created consumer config at ${consumerPath}`));
     if (!producerName) {
       console.log(import_chalk12.default.blue("Remember to:"));
@@ -54348,8 +54563,8 @@ init_src5();
 var import_chalk13 = __toESM(require("chalk"));
 var import_ora5 = __toESM(require("ora"));
 init_src10();
-var import_fs23 = __toESM(require("fs"));
-var import_path31 = __toESM(require("path"));
+var import_fs24 = __toESM(require("fs"));
+var import_path32 = __toESM(require("path"));
 init_src4();
 init_src10();
 init_src2();
@@ -54378,14 +54593,14 @@ var automap = async (producerName, schemaNames) => {
     const mapResult = await AutoMapperEngine_default.map(sampleStrings, schemas, producer.settings.fileKey, [source]);
     for (const producer2 of mapResult.producers) {
       const producerPath = Environment_default.resolveResourceFilePath("producers", producer2.name);
-      import_fs23.default.mkdirSync(import_path31.default.dirname(producerPath), { recursive: true });
-      import_fs23.default.writeFileSync(producerPath, JSON.stringify(producer2, null, 4));
+      import_fs24.default.mkdirSync(import_path32.default.dirname(producerPath), { recursive: true });
+      import_fs24.default.writeFileSync(producerPath, JSON.stringify(producer2, null, 4));
       console.log(import_chalk13.default.blue(`Created producer: ${producer2.name}`));
     }
     for (const consumer of mapResult.consumers) {
       const consumerPath = Environment_default.resolveResourceFilePath("consumers", consumer.name);
-      import_fs23.default.mkdirSync(import_path31.default.dirname(consumerPath), { recursive: true });
-      import_fs23.default.writeFileSync(consumerPath, JSON.stringify(consumer, null, 4));
+      import_fs24.default.mkdirSync(import_path32.default.dirname(consumerPath), { recursive: true });
+      import_fs24.default.writeFileSync(consumerPath, JSON.stringify(consumer, null, 4));
       console.log(import_chalk13.default.blue(`Created consumer: ${consumer.name}`));
     }
     spinner.succeed("Producer has been successfully mapped");
@@ -54405,7 +54620,6 @@ var automap = async (producerName, schemaNames) => {
 // src/actions/sample.ts
 var import_chalk14 = __toESM(require("chalk"));
 var import_ora6 = __toESM(require("ora"));
-init_src10();
 init_src5();
 init_src2();
 var sample = async (resourceName, sampleSize = 10) => {
@@ -54413,8 +54627,9 @@ var sample = async (resourceName, sampleSize = 10) => {
     compile();
     console.log();
     const spinner = (0, import_ora6.default)(import_chalk14.default.blue(`Sampling "${resourceName}"...`)).start();
-    const { kind, records } = await SampleEngine_default.read(resourceName, sampleSize);
+    const { kind, records, note } = await SampleRunner_default.read(resourceName, sampleSize);
     spinner.succeed(import_chalk14.default.green(`Sample data retrieved from ${kind} "${resourceName}"`));
+    console.log(import_chalk14.default.gray(`   ${note}`));
     if (records.length === 0) {
       console.log(import_chalk14.default.yellow("No data found in the dataset."));
       return;
@@ -54619,7 +54834,7 @@ program.command("deploy").description("Deploy the application to the specified e
 program.command("run [name]").description("Execute consumers. Optionally specify a single consumer name or use --project to run all consumers in a project.").option("-p, --project <name>", "Run all consumers belonging to the specified project").option("-l, --limit <number>", "Limit the number of output records", parseInt).action((name, options) => run(name, options));
 program.command("discover").description("Discover the data shape of a producer and automatically create the resource for it.").argument("<producer>", "The producer to discover").action(discover);
 program.command("graph").description("Print the project lineage (what feeds what) to stdout as a diagram or as JSON").option("-f, --format <format>", "Output format: mermaid, dot or json", "mermaid").action((options) => graph(options));
-program.command("ui-preview").description("Open a read-only visual preview of the project: the lineage graph, and a table inspector for every resource").option("-p, --port <number>", "Port to serve the preview on (default: 5070, or the next free one)").option("--no-open", "Do not open a browser window").action((options) => ui_preview(options));
+program.command("ui-preview").description("Open a visual preview of the project: the lineage graph, and a table inspector for every resource").option("-p, --port <number>", "Port to serve the preview on (default: 5070, or the next free one)").option("--no-open", "Do not open a browser window").action((options) => ui_preview(options));
 program.command("create-producer <name>").description("Create a new producer configuration with default settings").action(create_producer);
 program.command("automap").description("Automatically map a producer to consumers using specified schemas.").argument("<producer>", "The producer to analyze").argument("<schemas...>", "One or more schema names to map against").action(automap);
 program.command("create-consumer <name>").description("Create a new consumer configuration with default settings").option("-p, --producer <name>", "Producer to create a one-to-one mapping from").action((name, options) => create_consumer(name, options.producer));