@ak--47/dungeon-master 1.4.0 → 1.4.2

package/index.js

@@ -18,14 +18,14 @@ import { detectInputType, loadFromFile, loadFromText, parseJSONDungeon, validate
 
 // Orchestrators
 import { userLoop } from './lib/orchestrators/user-loop.js';
-import { sendToMixpanel } from './lib/orchestrators/mixpanel-sender.js';
+import { sendToMixpanel, collectWrittenFiles } from './lib/orchestrators/mixpanel-sender.js';
 // Generators
 import { makeAdSpend } from './lib/generators/adspend.js';
 import { makeMirror } from './lib/generators/mirror.js';
 import { makeGroupProfile, makeProfile } from './lib/generators/profiles.js';
 
 // Utilities
-import { initChance, setDatasetNow } from './lib/utils/utils.js';
+import { initChance, setDatasetNow, deleteFile } from './lib/utils/utils.js';
 
 // External dependencies
 import dayjs from "dayjs";
@@ -122,6 +122,7 @@ async function runDungeon(config) {
 
 	if (config.verbose) logger.info({ seed: config.seed }, 'Configuring dungeon');
 	let validatedConfig;
+	let storage;
 	try {
 		// Initialize seeded RNG BEFORE validation — config-validator captures a
 		// chance reference for default userProps (spiritAnimal). If we init after,
@@ -148,7 +149,7 @@ async function runDungeon(config) {
 
 		// Step 3: Initialize storage containers
 		const storageManager = new StorageManager(context);
-		const storage = await storageManager.initializeContainers();
+		storage = await storageManager.initializeContainers();
 		updateContextWithStorage(context, storage);
 
 		// ! DATA GENERATION STARTS HERE
@@ -215,7 +216,7 @@ async function runDungeon(config) {
 		return {
 			...extractedData,
 			importResults,
-			files: await extractFileInfo(storage, validatedConfig),
+			files: extractFileInfo(storage),
 			time: { start, end, delta, human },
 			operations: context.getOperations(),
 			eventCount: context.getStoredEventCount(),
@@ -225,6 +226,15 @@ async function runDungeon(config) {
 	} catch (error) {
 		logger.error({ err: error }, `Error: ${error.message}`);
 		throw error;
+	} finally {
+		if (validatedConfig?.cleanup && storage) {
+			const allFiles = collectWrittenFiles(storage);
+			if (allFiles.length > 0) {
+				if (validatedConfig.verbose) console.log(`\nCleaning up ${allFiles.length} written files...`);
+				await Promise.allSettled(allFiles.map(f => deleteFile(f)));
+				if (validatedConfig.verbose) console.log(`Cleanup complete`);
+			}
+		}
 	}
 }
 
@@ -480,74 +490,10 @@ async function flushStorageToDisk(storage, config) {
 /**
  * Extract file information from storage containers
  * @param {import('./types').Storage} storage - Storage object
- * @param {import('./types').Dungeon} config - Configuration object
- * @returns {Promise<string[]>} Array of file paths
+ * @returns {string[]} Array of file paths
  */
-async function extractFileInfo(storage, config) {
-	const files = [];
-
-	// Try to get paths from containers first
-	Object.values(storage).forEach(container => {
-		if (Array.isArray(container)) {
-			container.forEach(subContainer => {
-				if (subContainer?.getWritePath) {
-					files.push(subContainer.getWritePath());
-				}
-			});
-		} else if (container?.getWritePath) {
-			files.push(container.getWritePath());
-		}
-	});
-
-	// If no files found from containers and writeToDisk is enabled, scan the data directory
-	if (files.length === 0 && config.writeToDisk) {
-		try {
-			const fs = await import('fs');
-			const path = await import('path');
-			
-			let dataDir = path.resolve("./data");
-			if (!fs.existsSync(dataDir)) {
-				dataDir = path.resolve("./");
-			}
-			
-			if (fs.existsSync(dataDir)) {
-				const allFiles = fs.readdirSync(dataDir);
-				const simulationName = config.name;
-				
-				// Filter files that match our patterns and were likely created by this run
-				const relevantFiles = allFiles.filter(file => {
-					// Skip system files
-					if (file.startsWith('.')) return false;
-					
-					// If we have a simulation name, only include files with that prefix
-					if (simulationName && !file.startsWith(simulationName)) {
-						return false;
-					}
-					
-					// Check for common patterns
-					const hasEventPattern = file.includes('-EVENTS.');
-					const hasUserPattern = file.includes('-USERS.');
-					const hasScdPattern = file.includes('-SCD.');
-					const hasGroupPattern = file.includes('-GROUPS.');
-					const hasLookupPattern = file.includes('-LOOKUP.');
-					const hasAdspendPattern = file.includes('-ADSPEND.');
-					const hasMirrorPattern = file.includes('-MIRROR.');
-					
-					return hasEventPattern || hasUserPattern || hasScdPattern || 
-						   hasGroupPattern || hasLookupPattern || hasAdspendPattern || hasMirrorPattern;
-				});
-				
-				// Convert to full paths
-				relevantFiles.forEach(file => {
-					files.push(path.join(dataDir, file));
-				});
-			}
-		} catch (error) {
-			// If scanning fails, just return empty array
-		}
-	}
-
-	return files;
+function extractFileInfo(storage) {
+	return collectWrittenFiles(storage);
 }
 
 /**

package/lib/core/config-validator.js

@@ -30,7 +30,7 @@ import { resolveMacro } from "../templates/macro-presets.js";
  * @param {number} [userNumDays]
  * @returns {{ datasetStartUnix: number, datasetEndUnix: number, numDays: number }}
  */
-function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays) {
+function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays, verbose = false) {
 	const hasStart = datasetStart !== undefined && datasetStart !== null;
 	const hasEnd = datasetEnd !== undefined && datasetEnd !== null;
 
@@ -48,7 +48,7 @@ function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays) {
 			throw new Error(`datasetEnd (${datasetEnd}) must be after datasetStart (${datasetStart}).`);
 		}
 		const derivedNumDays = Math.max(1, Math.round((endUnix - startUnix) / 86400));
-		if (userNumDays !== undefined && userNumDays !== null && userNumDays !== derivedNumDays) {
+		if (verbose && userNumDays !== undefined && userNumDays !== null && userNumDays !== derivedNumDays) {
 			console.warn(
 				`⚠️  datasetStart/datasetEnd take precedence; user-supplied numDays=${userNumDays} ignored, derived numDays=${derivedNumDays}.`
 			);
@@ -60,7 +60,7 @@ function resolveDatasetWindow(datasetStart, datasetEnd, userNumDays) {
 	const fallbackNumDays = (typeof userNumDays === 'number' && userNumDays > 0) ? userNumDays : 30;
 	const todayStart = dayjs().startOf('day').unix();
 	const fallbackStart = todayStart - fallbackNumDays * 86400;
-	console.warn(
+	if (verbose) console.warn(
 		`⚠️  No 'datasetStart'/'datasetEnd' set — dataset window anchored to today's date and will shift across runs. Pin both for full determinism.`
 	);
 	return { datasetStartUnix: fallbackStart, datasetEndUnix: todayStart, numDays: fallbackNumDays };
@@ -160,7 +160,7 @@ function stripKilledConfigKeys(config) {
 	const found = KILLED_CONFIG_KEYS.filter(k => config[k] !== undefined && config[k] !== null);
 	if (!found.length) return;
 	for (const k of found) delete config[k];
-	if (config.verbose !== false) {
+	if (config.verbose) {
 		console.warn(
 			`⚠️  dungeon-master 1.4 removed engine support for: ${found.join(', ')}. ` +
 			`These config keys are silently ignored. Recreate via hooks (see lib/hook-patterns/* once Phase 4 lands).`
@@ -346,7 +346,7 @@ export function validateDungeonConfig(config) {
 	// ── Resolve dataset window ──
 	// Preferred path: explicit datasetStart + datasetEnd → pinned, deterministic window.
 	// Fallback: numDays only → today_start - numDays back (sliding, warn-emitted).
-	const windowResolution = resolveDatasetWindow(config.datasetStart, config.datasetEnd, config.numDays);
+	const windowResolution = resolveDatasetWindow(config.datasetStart, config.datasetEnd, config.numDays, verbose);
 	const datasetStartUnix = windowResolution.datasetStartUnix;
 	const datasetEndUnix = windowResolution.datasetEndUnix;
 	numDays = windowResolution.numDays;
@@ -378,7 +378,7 @@ export function validateDungeonConfig(config) {
 	// only avgEventsPerUserPerDay would never trigger auto-batch.
 	if (numEvents >= 2_000_000 && config.batchSize === undefined) {
 		batchSize = 1_000_000;
-		console.warn(`⚠️  Auto-enabling batch mode: numEvents (${numEvents.toLocaleString()}) >= 2M. Using batchSize of ${batchSize.toLocaleString()}.`);
+		if (verbose) console.warn(`⚠️  Auto-enabling batch mode: numEvents (${numEvents.toLocaleString()}) >= 2M. Using batchSize of ${batchSize.toLocaleString()}.`);
 	}
 
 	// Resolve soup presets (intra-week / intra-day shape — must happen after numDays is computed)
@@ -422,7 +422,7 @@ export function validateDungeonConfig(config) {
 				throw new Error('Hook string did not evaluate to a function');
 			}
 		} catch (error) {
-			if (config.verbose !== false) {
+			if (verbose) {
 				console.warn(`\u26a0\ufe0f Failed to convert hook string to function: ${error.message}`);
 				console.warn('Using default pass-through hook');
 			}
@@ -432,7 +432,7 @@ export function validateDungeonConfig(config) {
 
 	// Ensure hook is a function
 	if (typeof hook !== 'function') {
-		if (config.verbose !== false) console.warn('\u26a0\ufe0f Hook is not a function, using default pass-through hook');
+		if (verbose) console.warn('\u26a0\ufe0f Hook is not a function, using default pass-through hook');
 		hook = (record) => record;
 	}
 
@@ -555,7 +555,7 @@ export function validateDungeonConfig(config) {
 
 	// Warn if isAuthEvent is set but avgDevicePerUser=0 — pre-auth device_only
 	// stamping degrades to user_id via the floor guard, defeating the identity model.
-	if (avgDevicePerUser === 0 && validatedEvents.some(e => e.isAuthEvent)) {
+	if (verbose && avgDevicePerUser === 0 && validatedEvents.some(e => e.isAuthEvent)) {
 		console.warn(
 			`⚠️  isAuthEvent requires avgDevicePerUser >= 1 to produce pre-auth anonymous events. ` +
 			`Set avgDevicePerUser or hasAnonIds: true.`

package/lib/core/storage.js

@@ -50,6 +50,7 @@ export async function createHookArray(arr = [], opts) {
 	let writeDir;
 	let isBatchMode = runtime.isBatchMode || false;
 	let isWriting = false; // Prevent concurrent writes
+	const writtenFiles = [];
 
 	// Determine write directory
 	const dataFolder = path.resolve("./data");
@@ -175,6 +176,7 @@ export async function createHookArray(arr = [], opts) {
 
 				// Write to disk/cloud - always blocking to prevent OOM
 				const writeResult = await FILE_CONN(() => writeToDisk(dataToWrite, { writePath }));
+				writtenFiles.push(writePath);
 				return writeResult;
 			} finally {
 				isWriting = false; // Release the lock
@@ -231,6 +233,7 @@ export async function createHookArray(arr = [], opts) {
 				const dataToWrite = [...arr];
 				arr.length = 0; // Clear array after copying data
 				await FILE_CONN(() => writeToDisk(dataToWrite, { writePath }));
+				writtenFiles.push(writePath);
 				// Data now lives on disk, not in arr — mirror what transformThenPush
 				// does when crossing BATCH_SIZE so the Mixpanel sender knows to read
 				// from disk instead of from the (now empty) in-memory array.
@@ -249,6 +252,7 @@ export async function createHookArray(arr = [], opts) {
 	enrichedArray.flush = flush;
 	enrichedArray.getWriteDir = getWriteDir;
 	enrichedArray.getWritePath = getWritePath;
+	enrichedArray.getWrittenFiles = () => [...writtenFiles];
 
 	// Add additional properties from rest
 	for (const key in rest) {
@@ -384,7 +388,7 @@ export class StorageManager {
 			const batchSize = config.batchSize || 1_000_000;
 			const numEvents = config.numEvents || 0;
 
-			if (batchSize < numEvents) {
+			if (batchSize < numEvents && config.verbose) {
 				console.warn(
 					`⚠️  writeToDisk is false but batchSize (${batchSize.toLocaleString()}) < numEvents (${numEvents.toLocaleString()}). ` +
 					`Batch files will be written to disk temporarily to avoid OOM. ` +

package/lib/orchestrators/mixpanel-sender.js

@@ -6,7 +6,7 @@
 /** @typedef {import('../../types').Context} Context */
 
 import dayjs from "dayjs";
-import { comma, ls, rm } from "ak-tools";
+import { comma, rm } from "ak-tools";
 import * as u from "../utils/utils.js";
 import mp from "mixpanel-import";
 
@@ -15,6 +15,8 @@ import mp from "mixpanel-import";
  * @param {Context} context - Context object containing config, storage, etc.
  * @returns {Promise<Object>} Import results for all data types
  */
+export { collectWrittenFiles };
+
 export async function sendToMixpanel(context) {
 	const { config, storage } = context;
 	const {
@@ -70,11 +72,9 @@ export async function sendToMixpanel(context) {
 		log(`  Events`);
 		let eventDataToImport = u.deepClone(eventData);
 		const shouldReadFromFiles = isBATCH_MODE || (writeToDisk && eventData && eventData.length === 0);
-		if (shouldReadFromFiles && eventData?.getWriteDir) {
-			const writeDir = eventData.getWriteDir();
-			const files = await ls(writeDir);
-			// @ts-ignore
-			eventDataToImport = files.filter(f => f.includes('-EVENTS'));
+		if (shouldReadFromFiles && eventData?.getWrittenFiles) {
+			const files = eventData.getWrittenFiles();
+			if (files.length > 0) eventDataToImport = files;
 		}
 		const imported = await mp(creds, eventDataToImport, {
 			recordType: "event",
@@ -89,11 +89,9 @@ export async function sendToMixpanel(context) {
 		log(`  User Profiles`);
 		let userProfilesToImport = u.deepClone(userProfilesData);
 		const shouldReadFromFiles = isBATCH_MODE || (writeToDisk && userProfilesData && userProfilesData.length === 0);
-		if (shouldReadFromFiles && userProfilesData?.getWriteDir) {
-			const writeDir = userProfilesData.getWriteDir();
-			const files = await ls(writeDir);
-			// @ts-ignore
-			userProfilesToImport = files.filter(f => f.includes('-USERS'));
+		if (shouldReadFromFiles && userProfilesData?.getWrittenFiles) {
+			const files = userProfilesData.getWrittenFiles();
+			if (files.length > 0) userProfilesToImport = files;
 		}
 		const imported = await mp(creds, userProfilesToImport, {
 			recordType: "user",
@@ -108,11 +106,9 @@ export async function sendToMixpanel(context) {
 		log(`  Ad Spend`);
 		let adSpendDataToImport = u.deepClone(adSpendData);
 		const shouldReadFromFiles = isBATCH_MODE || (writeToDisk && adSpendData && adSpendData.length === 0);
-		if (shouldReadFromFiles && adSpendData?.getWriteDir) {
-			const writeDir = adSpendData.getWriteDir();
-			const files = await ls(writeDir);
-			// @ts-ignore
-			adSpendDataToImport = files.filter(f => f.includes('-ADSPEND'));
+		if (shouldReadFromFiles && adSpendData?.getWrittenFiles) {
+			const files = adSpendData.getWrittenFiles();
+			if (files.length > 0) adSpendDataToImport = files;
 		}
 		const imported = await mp(creds, adSpendDataToImport, {
 			recordType: "event",
@@ -130,11 +126,9 @@ export async function sendToMixpanel(context) {
 			log(`  Group Profiles (${groupKey})`);
 			let groupProfilesToImport = u.deepClone(groupEntity);
 			const shouldReadFromFiles = isBATCH_MODE || (writeToDisk && groupEntity.length === 0);
-			if (shouldReadFromFiles && groupEntity?.getWriteDir) {
-				const writeDir = groupEntity.getWriteDir();
-				const files = await ls(writeDir);
-				// @ts-ignore
-				groupProfilesToImport = files.filter(f => f.includes(`-${groupKey}-GROUPS`));
+			if (shouldReadFromFiles && groupEntity?.getWrittenFiles) {
+				const files = groupEntity.getWrittenFiles();
+				if (files.length > 0) groupProfilesToImport = files;
 			}
 			const imported = await mp({ token, groupKey }, groupProfilesToImport, {
 				recordType: "group",
@@ -151,11 +145,9 @@ export async function sendToMixpanel(context) {
 		log(`  Group Events`);
 		let groupEventDataToImport = u.deepClone(groupEventData);
 		const shouldReadFromFiles = isBATCH_MODE || (writeToDisk && groupEventData.length === 0);
-		if (shouldReadFromFiles && groupEventData?.getWriteDir) {
-			const writeDir = groupEventData.getWriteDir();
-			const files = await ls(writeDir);
-			// @ts-ignore
-			groupEventDataToImport = files.filter(f => f.includes('-GROUP-EVENTS'));
+		if (shouldReadFromFiles && groupEventData?.getWrittenFiles) {
+			const files = groupEventData.getWrittenFiles();
+			if (files.length > 0) groupEventDataToImport = files;
 		}
 		const imported = await mp(creds, groupEventDataToImport, {
 			recordType: "event",
@@ -174,11 +166,9 @@ export async function sendToMixpanel(context) {
 				log(`  SCD: ${scdKey}`);
 				let scdDataToImport = u.deepClone(scdEntity);
 				const shouldReadFromFiles = isBATCH_MODE || (writeToDisk && scdEntity && scdEntity.length === 0);
-				if (shouldReadFromFiles && scdEntity?.getWriteDir) {
-					const writeDir = scdEntity.getWriteDir();
-					const files = await ls(writeDir);
-					// @ts-ignore
-					scdDataToImport = files.filter(f => f.includes(`-${scdKey}-SCD`))?.pop();
+				if (shouldReadFromFiles && scdEntity?.getWrittenFiles) {
+					const files = scdEntity.getWrittenFiles();
+					if (files.length > 0) scdDataToImport = files;
 				}
 
 				/** @type {"string" | "number" | "boolean"} */
@@ -231,27 +221,11 @@ export async function sendToMixpanel(context) {
 
 	log(`${'─'.repeat(50)}\n`);
 
-	// Clean up batch files if needed
+	// Clean up batch files if needed (writeToDisk=false but batch mode wrote temp files)
 	if (!writeToDisk && isBATCH_MODE) {
-		const writeDir = eventData?.getWriteDir?.() || userProfilesData?.getWriteDir?.();
-		if (writeDir) {
-			const configName = context.config.name;
-			const listDir = await ls(writeDir);
-			// @ts-ignore
-			const files = listDir.filter(f => {
-				if (configName && !f.includes(configName)) return false;
-				return f.includes('-EVENTS') ||
-					f.includes('-USERS') ||
-					f.includes('-ADSPEND') ||
-					f.includes('-GROUPS') ||
-					f.includes('-GROUP-EVENTS') ||
-					f.includes('-SCD') ||
-					f.includes('-MIRROR') ||
-					f.includes('-LOOKUP');
-			});
-			for (const file of files) {
-				await rm(file);
-			}
+		const allFiles = collectWrittenFiles(storage);
+		for (const file of allFiles) {
+			await rm(file);
 		}
 	}
 
@@ -324,4 +298,25 @@ function logProblems(problems) {
 		}
 	}
 	log('');
+}
+
+/**
+ * Collect all written file paths from every storage container.
+ * @param {import('../../types').Storage} storage
+ * @returns {string[]}
+ */
+function collectWrittenFiles(storage) {
+	const files = [];
+	for (const container of [storage.eventData, storage.userProfilesData, storage.adSpendData,
+		storage.mirrorEventData, storage.groupEventData]) {
+		if (container?.getWrittenFiles) files.push(...container.getWrittenFiles());
+	}
+	for (const arr of [storage.groupProfilesData, storage.scdTableData, storage.lookupTableData]) {
+		if (Array.isArray(arr)) {
+			for (const c of arr) {
+				if (c?.getWrittenFiles) files.push(...c.getWrittenFiles());
+			}
+		}
+	}
+	return files;
 }

package/lib/templates/macro-presets.js

@@ -31,7 +31,7 @@ export const MACRO_PRESETS = {
 	 */
 	flat: {
 		bornRecentBias: 0,
-		percentUsersBornInDataset: 15,
+		percentUsersBornInDataset: 50,
 		preExistingSpread: 'uniform',
 	},
 
@@ -41,7 +41,7 @@ export const MACRO_PRESETS = {
 	 */
 	steady: {
 		bornRecentBias: 0.1,
-		percentUsersBornInDataset: 10,
+		percentUsersBornInDataset: 35,
 		preExistingSpread: 'uniform',
 	},
 
@@ -51,7 +51,7 @@ export const MACRO_PRESETS = {
 	 */
 	growth: {
 		bornRecentBias: 0.3,
-		percentUsersBornInDataset: 25,
+		percentUsersBornInDataset: 60,
 		preExistingSpread: 'pinned',
 	},
 
@@ -61,7 +61,7 @@ export const MACRO_PRESETS = {
 	 */
 	viral: {
 		bornRecentBias: 0.6,
-		percentUsersBornInDataset: 50,
+		percentUsersBornInDataset: 95,
 		preExistingSpread: 'pinned',
 	},
 
@@ -71,7 +71,7 @@ export const MACRO_PRESETS = {
 	 */
 	decline: {
 		bornRecentBias: -0.3,
-		percentUsersBornInDataset: 5,
+		percentUsersBornInDataset: 25,
 		preExistingSpread: 'uniform',
 	},
 };

package/lib/utils/utils.js

@@ -1597,6 +1597,15 @@ function assignSessionIds(events, timeoutMinutes = 30) {
 	return events;
 }
 
+async function deleteFile(filePath) {
+	if (filePath.startsWith('gs://')) {
+		const { bucket, file } = parseGCSUri(filePath);
+		await storage.bucket(bucket).file(file).delete({ ignoreNotFound: true });
+	} else {
+		await fs.promises.unlink(filePath).catch(() => {});
+	}
+}
+
 export {
 	pick,
 	date,
@@ -1651,4 +1660,5 @@ export {
 	assignSessionIds,
 	bunchIntoSessions,
 	setDatasetNow,
+	deleteFile,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ak--47/dungeon-master",
-	"version": "1.4.0",
+	"version": "1.4.2",
 	"description": "generate fancy datasets",
 	"type": "module",
 	"main": "index.js",

package/types.d.ts

@@ -19,6 +19,8 @@ export interface Dungeon {
     // ── Core Parameters ──
     /** Optional dungeon version. Not used by the engine — serves as metadata for tracking revisions when configs are saved/shared. */
     version?: string | number;
+    /** Optional app or dataset name. Not used by the engine — available for logging and metadata when set. */
+    appName?: string;
     /** Mixpanel project token. If provided, data will be imported to Mixpanel after generation. */
     token?: string;
     /** RNG seed for reproducible output. Same seed + concurrency=1 = identical data. */
@@ -109,8 +111,10 @@ export interface Dungeon {
     hasDesktopDevices?: boolean;
     /** If true, events include browser properties. */
     hasBrowser?: boolean;
-    /** If true (default), writes output files to ./data/. Can also be a directory path string. */
+    /** If true (default), writes output files to ./data/. Can also be a directory path string or gs:// URI. */
     writeToDisk?: boolean | string;
+    /** If true, deletes all written files (local and GCS) at end of run regardless of import success/failure. Default: false. */
+    cleanup?: boolean;
     /** If true, gzip-compresses output files. */
     gzip?: boolean;
     /** If true, prints progress to stdout during generation. */
@@ -220,7 +224,7 @@ export interface Dungeon {
     // ── Distribution Controls ──
     // These three knobs are normally set by the `macro` preset (default "flat").
     // Setting them on the dungeon config directly overrides the preset's value.
-    /** Percentage of users whose account creation falls within the dataset window (vs. pre-existing). Default (from macro: "flat"): 15 */
+    /** Percentage of users whose account creation falls within the dataset window (vs. pre-existing). Default (from macro: "flat"): 50 */
     percentUsersBornInDataset?: number;
     /** Bias for birth dates of users born in dataset. -1..1; negative = early skew, positive = recent skew, 0 = uniform. Default (from macro: "flat"): 0 */
     bornRecentBias?: number;
@@ -541,6 +545,8 @@ export interface HookedArray<T> extends Array<T> {
     getWriteDir: () => string;
     /** Absolute path (with extension) of the next batch file. */
     getWritePath: () => string;
+    /** Returns all file paths written by this container during the current run. */
+    getWrittenFiles: () => string[];
     /** SCD prop name this array carries (only set on SCD HookedArrays). */
     scdKey?: string;
     /** Entity type for SCDs ("user" or a group key). */