@workflow/world-local 5.0.0-beta.10 → 5.0.0-beta.3

package/dist/config.d.ts

@@ -3,17 +3,29 @@ export type Config = {
     dataDir: string;
     port?: number;
     baseUrl?: string;
+    /**
+     * Optional tag to scope filesystem operations.
+     * When set, files are written as `{id}.{tag}.json` and `clear()` only deletes
+     * files matching this tag. Used by vitest to isolate test data in the shared
+     * `.workflow-data` directory.
+     */
+    tag?: string;
+    /**
+     * Override the flush interval (in ms) for buffered stream writes.
+     * Default is 10ms. Set to 0 for immediate flushing.
+     */
+    streamFlushIntervalMs?: number;
 };
 export declare const config: {
     readonly value: Config;
 };
 /**
  * Resolves the base URL for queue requests following the priority order:
- * 1. config.baseUrl (highest priority - full override from args or WORKFLOW_EMBEDDED_BASE_URL env var)
- * 2. config.port (explicit port override from args)
- * 3. Auto-detected port via pid-port (primary approach)
- * 4. PORT env var (fallback)
- * 5. Fallback to 3000
+ * 1. config.baseUrl (highest priority - full override from args)
+ * 2. WORKFLOW_LOCAL_BASE_URL env var (checked directly to handle late env var setting)
+ * 3. config.port (explicit port override from args)
+ * 4. PORT env var (explicit configuration)
+ * 5. Auto-detected port via getPort (detect actual listening port)
  */
 export declare function resolveBaseUrl(config: Partial<Config>): Promise<string>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAMjD,MAAM,MAAM,MAAM,GAAG;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,MAAM;;CAKjB,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAmB7E"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AAMjD,MAAM,MAAM,MAAM,GAAG;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,CAAC;AAEF,eAAO,MAAM,MAAM;;CAKjB,CAAC;AAEH;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAyB7E"}

package/dist/config.js

@@ -1,11 +1,11 @@
-import { getPort } from '@workflow/utils/get-port';
+import { getWorkflowPort } from '@workflow/utils/get-port';
 import { once } from './util.js';
 const getDataDirFromEnv = () => {
-    return process.env.WORKFLOW_EMBEDDED_DATA_DIR || '.workflow-data';
+    return process.env.WORKFLOW_LOCAL_DATA_DIR || '.workflow-data';
 };
 export const DEFAULT_RESOLVE_DATA_OPTION = 'all';
 const getBaseUrlFromEnv = () => {
-    return process.env.WORKFLOW_EMBEDDED_BASE_URL;
+    return process.env.WORKFLOW_LOCAL_BASE_URL;
 };
 export const config = once(() => {
     const dataDir = getDataDirFromEnv();
@@ -14,26 +14,31 @@ export const config = once(() => {
 });
 /**
  * Resolves the base URL for queue requests following the priority order:
- * 1. config.baseUrl (highest priority - full override from args or WORKFLOW_EMBEDDED_BASE_URL env var)
- * 2. config.port (explicit port override from args)
- * 3. Auto-detected port via pid-port (primary approach)
- * 4. PORT env var (fallback)
- * 5. Fallback to 3000
+ * 1. config.baseUrl (highest priority - full override from args)
+ * 2. WORKFLOW_LOCAL_BASE_URL env var (checked directly to handle late env var setting)
+ * 3. config.port (explicit port override from args)
+ * 4. PORT env var (explicit configuration)
+ * 5. Auto-detected port via getPort (detect actual listening port)
  */
 export async function resolveBaseUrl(config) {
     if (config.baseUrl) {
         return config.baseUrl;
     }
+    // Check env var directly in case it was set after the config was cached
+    // This is important for CLI tools that set the env var after module import
+    if (process.env.WORKFLOW_LOCAL_BASE_URL) {
+        return process.env.WORKFLOW_LOCAL_BASE_URL;
+    }
     if (typeof config.port === 'number') {
         return `http://localhost:${config.port}`;
     }
-    const detectedPort = await getPort();
-    if (detectedPort) {
-        return `http://localhost:${detectedPort}`;
-    }
     if (process.env.PORT) {
         return `http://localhost:${process.env.PORT}`;
     }
-    return 'http://localhost:3000';
+    const detectedPort = await getWorkflowPort();
+    if (detectedPort) {
+        return `http://localhost:${detectedPort}`;
+    }
+    throw new Error('Unable to resolve base URL for workflow queue.');
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,iBAAiB,GAAG,GAAG,EAAE;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,0BAA0B,IAAI,gBAAgB,CAAC;AACpE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD,MAAM,iBAAiB,GAAG,GAAG,EAAE;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;AAChD,CAAC,CAAC;AAQF,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAS,GAAG,EAAE;IACtC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IAEpC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAuB;IAC1D,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,oBAAoB,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,OAAO,EAAE,CAAC;IACrC,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,oBAAoB,YAAY,EAAE,CAAC;IAC5C,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACrB,OAAO,oBAAoB,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAChD,CAAC;IAED,OAAO,uBAAuB,CAAC;AACjC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,iBAAiB,GAAG,GAAG,EAAE;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,gBAAgB,CAAC;AACjE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD,MAAM,iBAAiB,GAAG,GAAG,EAAE;IAC7B,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;AAC7C,CAAC,CAAC;AAoBF,MAAM,CAAC,MAAM,MAAM,GAAG,IAAI,CAAS,GAAG,EAAE;IACtC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,iBAAiB,EAAE,CAAC;IAEpC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC,CAAC,CAAC;AAEH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,MAAuB;IAC1D,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC;IAED,wEAAwE;IACxE,2EAA2E;IAC3E,IAAI,OAAO,CAAC,GAAG,CAAC,uBAAuB,EAAE,CAAC;QACxC,OAAO,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IAC7C,CAAC;IAED,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACpC,OAAO,oBAAoB,MAAM,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QACrB,OAAO,oBAAoB,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,eAAe,EAAE,CAAC;IAC7C,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,oBAAoB,YAAY,EAAE,CAAC;IAC5C,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;AACpE,CAAC","sourcesContent":["import { getWorkflowPort } from '@workflow/utils/get-port';\nimport { once } from './util.js';\n\nconst getDataDirFromEnv = () => {\n  return process.env.WORKFLOW_LOCAL_DATA_DIR || '.workflow-data';\n};\n\nexport const DEFAULT_RESOLVE_DATA_OPTION = 'all';\n\nconst getBaseUrlFromEnv = () => {\n  return process.env.WORKFLOW_LOCAL_BASE_URL;\n};\n\nexport type Config = {\n  dataDir: string;\n  port?: number;\n  baseUrl?: string;\n  /**\n   * Optional tag to scope filesystem operations.\n   * When set, files are written as `{id}.{tag}.json` and `clear()` only deletes\n   * files matching this tag. Used by vitest to isolate test data in the shared\n   * `.workflow-data` directory.\n   */\n  tag?: string;\n  /**\n   * Override the flush interval (in ms) for buffered stream writes.\n   * Default is 10ms. Set to 0 for immediate flushing.\n   */\n  streamFlushIntervalMs?: number;\n};\n\nexport const config = once<Config>(() => {\n  const dataDir = getDataDirFromEnv();\n  const baseUrl = getBaseUrlFromEnv();\n\n  return { dataDir, baseUrl };\n});\n\n/**\n * Resolves the base URL for queue requests following the priority order:\n * 1. config.baseUrl (highest priority - full override from args)\n * 2. WORKFLOW_LOCAL_BASE_URL env var (checked directly to handle late env var setting)\n * 3. config.port (explicit port override from args)\n * 4. PORT env var (explicit configuration)\n * 5. Auto-detected port via getPort (detect actual listening port)\n */\nexport async function resolveBaseUrl(config: Partial<Config>): Promise<string> {\n  if (config.baseUrl) {\n    return config.baseUrl;\n  }\n\n  // Check env var directly in case it was set after the config was cached\n  // This is important for CLI tools that set the env var after module import\n  if (process.env.WORKFLOW_LOCAL_BASE_URL) {\n    return process.env.WORKFLOW_LOCAL_BASE_URL;\n  }\n\n  if (typeof config.port === 'number') {\n    return `http://localhost:${config.port}`;\n  }\n\n  if (process.env.PORT) {\n    return `http://localhost:${process.env.PORT}`;\n  }\n\n  const detectedPort = await getWorkflowPort();\n  if (detectedPort) {\n    return `http://localhost:${detectedPort}`;\n  }\n\n  throw new Error('Unable to resolve base URL for workflow queue.');\n}\n"]}

package/dist/fs.d.ts

@@ -1,16 +1,117 @@
+import { WorkflowWorldError } from '@workflow/errors';
 import type { PaginatedResponse } from '@workflow/world';
 import { z } from 'zod';
-export declare function ulidToDate(maybeUlid: string): Date | null;
+/**
+ * Thrown when a caller-supplied entity ID contains characters that would
+ * escape the storage root (path traversal) or otherwise produce an unsafe
+ * filename. Extends {@link WorkflowWorldError} so the platform's standard
+ * error-to-HTTP mapping handles it alongside other world-layer errors.
+ */
+export declare class UnsafeEntityIdError extends WorkflowWorldError {
+    constructor(kind: string, value: string);
+    static is(value: unknown): value is UnsafeEntityIdError;
+}
+/**
+ * Validate that a string is safe to embed in a filesystem path as a single
+ * path component. Rejects values that are:
+ *   - empty
+ *   - starting with `.` (blocks `.`, `..`, `.locks`, `.tmp`, and other
+ *     hidden or reserved filenames)
+ *   - containing `/`, `\`, or a NUL byte
+ *
+ * This is the primary defense against path-traversal attacks where a
+ * request body supplies a `runId` / `stepId` / `correlationId` containing
+ * `../` sequences to read or write files outside the storage root.
+ * {@link resolveWithinBase} provides a belt-and-suspenders containment
+ * check at the point of `path.join` for defense in depth.
+ *
+ * @param kind - Human-readable label used in the error message (e.g. "runId")
+ * @param value - The value to validate; throws {@link UnsafeEntityIdError}
+ *   if the value is not safe.
+ */
+export declare function assertSafeEntityId(kind: string, value: string): void;
+/**
+ * Join `basedir` with an entity-relative path and assert the result stays
+ * inside `basedir`. Complements {@link assertSafeEntityId}: per-entry-point
+ * validation is the primary defense, and this final check catches any path
+ * escape that slipped past (e.g. a new call site that forgot to validate,
+ * or an unusual character combination on a future filesystem). Throws
+ * {@link UnsafeEntityIdError} if the joined path escapes `basedir`.
+ */
+export declare function resolveWithinBase(basedir: string, ...segments: string[]): string;
+/**
+ * Clear the created files cache. Useful for testing or when files are deleted externally.
+ */
+export declare function clearCreatedFilesCache(): void;
+export { ulidToDate } from '@workflow/world';
+/**
+ * Strip a tag suffix from a fileId.
+ * `wrun_ABC.vitest-0` → `wrun_ABC`
+ * `wrun_ABC` → `wrun_ABC` (no-op if no tag)
+ */
+export declare function stripTag(fileId: string): string;
+/**
+ * Build the file path for an entity, with optional tag embedded in the filename.
+ * `taggedPath('/data', 'runs', 'wrun_ABC', 'vitest-0')` → `/data/runs/wrun_ABC.vitest-0.json`
+ * `taggedPath('/data', 'runs', 'wrun_ABC')` → `/data/runs/wrun_ABC.json`
+ *
+ * The `fileId` and `tag` are validated with {@link assertSafeEntityId} and
+ * the result is containment-checked with {@link resolveWithinBase} to
+ * prevent path-traversal attacks when values are derived from untrusted
+ * request input.
+ */
+export declare function taggedPath(basedir: string, entityDir: string, fileId: string, tag?: string): string;
+/**
+ * Read a JSON entity with tagged fallback.
+ * When a tag is set, tries the tagged path first, then falls back to the
+ * untagged path (so a tagged world can read entities written without a tag).
+ */
+export declare function readJSONWithFallback<T>(basedir: string, entityDir: string, fileId: string, schema: z.ZodType<T>, tag?: string): Promise<T | null>;
+/**
+ * List all filenames in a directory that have a specific tag.
+ * Returns full filenames (e.g., `wrun_ABC.vitest-0.json`).
+ */
+export declare function listTaggedFiles(dirPath: string, tag: string): Promise<string[]>;
+/**
+ * List all filenames in a directory that have a specific tag and extension.
+ * Returns full filenames (e.g., `stream-chnk_ABC.vitest-0.bin`).
+ */
+export declare function listTaggedFilesByExtension(dirPath: string, tag: string, extension: string): Promise<string[]>;
 export declare function ensureDir(dirPath: string): Promise<void>;
 interface WriteOptions {
     overwrite?: boolean;
 }
+/**
+ * Custom JSON replacer that encodes Uint8Array as base64 strings.
+ * Format: { __type: 'Uint8Array', data: '<base64>' }
+ */
+export declare function jsonReplacer(_key: string, value: unknown): unknown;
+/**
+ * Custom JSON reviver that decodes base64 strings back to Uint8Array.
+ */
+export declare function jsonReviver(_key: string, value: unknown): unknown;
 export declare function writeJSON(filePath: string, data: any, opts?: WriteOptions): Promise<void>;
+/**
+ * Writes data to a file using atomic write-rename pattern.
+ *
+ * Note: While this function uses temp files to avoid partial writes,
+ * it does not provide protection against concurrent writes from multiple
+ * processes. In a multi-writer scenario, the last writer wins.
+ * For production use with multiple writers, consider using a proper
+ * database or locking mechanism.
+ */
 export declare function write(filePath: string, data: string | Buffer, opts?: WriteOptions): Promise<void>;
 export declare function readJSON<T>(filePath: string, decoder: z.ZodType<T>): Promise<T | null>;
 export declare function readBuffer(filePath: string): Promise<Buffer>;
 export declare function deleteJSON(filePath: string): Promise<void>;
+/**
+ * Atomically create a file using O_CREAT | O_EXCL flags.
+ * Returns true if the file was created, false if it already exists.
+ * This is atomic at the OS level, safe for concurrent access.
+ */
+export declare function writeExclusive(filePath: string, data: string): Promise<boolean>;
 export declare function listJSONFiles(dirPath: string): Promise<string[]>;
+export declare function listFilesByExtension(dirPath: string, extension: string): Promise<string[]>;
 interface PaginatedFileSystemQueryConfig<T> {
     directory: string;
     schema: z.ZodType<T>;
@@ -25,5 +126,4 @@ interface PaginatedFileSystemQueryConfig<T> {
 export declare function paginatedFileSystemQuery<T extends {
     createdAt: Date;
 }>(config: PaginatedFileSystemQueryConfig<T>): Promise<PaginatedResponse<T>>;
-export {};
 //# sourceMappingURL=fs.d.ts.map

package/dist/fs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAOzD;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9D;AAED,UAAU,YAAY;IACpB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,GAAG,EACT,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,KAAK,CACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,IAAI,CAAC,EAAE,YAAY,GAClB,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,QAAQ,CAAC,CAAC,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAQnB;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGlE;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMhE;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAUtE;AAED,UAAU,8BAA8B,CAAC,CAAC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IAC9B,SAAS,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAC5C,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,MAAM,CAAC;CACzB;AAqBD,wBAAsB,wBAAwB,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,EAC1E,MAAM,EAAE,8BAA8B,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAoI/B"}
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"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"}

package/dist/fs.js

@@ -1,16 +1,196 @@
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
-import { WorkflowAPIError } from '@workflow/errors';
-import { decodeTime, monotonicFactory } from 'ulid';
+import { EntityConflictError, WorkflowWorldError } from '@workflow/errors';
+import { monotonicFactory } from 'ulid';
 import { z } from 'zod';
 const ulid = monotonicFactory(() => Math.random());
-const Ulid = z.string().ulid();
-export function ulidToDate(maybeUlid) {
-    const ulid = Ulid.safeParse(maybeUlid);
-    if (!ulid.success) {
-        return null;
+/**
+ * Truncate a possibly-untrusted value for inclusion in an error message.
+ * Keeps error output actionable for developers in dev mode while limiting
+ * the amount of attacker-controlled data reflected back if a `world-local`
+ * backend is ever run in a context that surfaces these messages to clients.
+ */
+function truncateForError(value) {
+    const s = typeof value === 'string' ? value : String(value);
+    const MAX = 48;
+    return s.length > MAX ? `${s.slice(0, MAX)}…` : s;
+}
+/**
+ * Thrown when a caller-supplied entity ID contains characters that would
+ * escape the storage root (path traversal) or otherwise produce an unsafe
+ * filename. Extends {@link WorkflowWorldError} so the platform's standard
+ * error-to-HTTP mapping handles it alongside other world-layer errors.
+ */
+export class UnsafeEntityIdError extends WorkflowWorldError {
+    constructor(kind, value) {
+        super(`Unsafe ${kind} "${truncateForError(value)}": must not be empty, start with ".", or contain path separators or null bytes`);
+        this.name = 'UnsafeEntityIdError';
+    }
+    static is(value) {
+        return value instanceof Error && value.name === 'UnsafeEntityIdError';
+    }
+}
+/**
+ * Validate that a string is safe to embed in a filesystem path as a single
+ * path component. Rejects values that are:
+ *   - empty
+ *   - starting with `.` (blocks `.`, `..`, `.locks`, `.tmp`, and other
+ *     hidden or reserved filenames)
+ *   - containing `/`, `\`, or a NUL byte
+ *
+ * This is the primary defense against path-traversal attacks where a
+ * request body supplies a `runId` / `stepId` / `correlationId` containing
+ * `../` sequences to read or write files outside the storage root.
+ * {@link resolveWithinBase} provides a belt-and-suspenders containment
+ * check at the point of `path.join` for defense in depth.
+ *
+ * @param kind - Human-readable label used in the error message (e.g. "runId")
+ * @param value - The value to validate; throws {@link UnsafeEntityIdError}
+ *   if the value is not safe.
+ */
+export function assertSafeEntityId(kind, value) {
+    if (value.length === 0 ||
+        value.startsWith('.') ||
+        value.includes('/') ||
+        value.includes('\\') ||
+        value.includes('\0')) {
+        throw new UnsafeEntityIdError(kind, value);
+    }
+}
+/**
+ * Join `basedir` with an entity-relative path and assert the result stays
+ * inside `basedir`. Complements {@link assertSafeEntityId}: per-entry-point
+ * validation is the primary defense, and this final check catches any path
+ * escape that slipped past (e.g. a new call site that forgot to validate,
+ * or an unusual character combination on a future filesystem). Throws
+ * {@link UnsafeEntityIdError} if the joined path escapes `basedir`.
+ */
+export function resolveWithinBase(basedir, ...segments) {
+    const resolvedBase = path.resolve(basedir);
+    const joined = path.resolve(basedir, ...segments);
+    if (joined !== resolvedBase && !joined.startsWith(resolvedBase + path.sep)) {
+        throw new UnsafeEntityIdError('path', segments.join('/'));
+    }
+    return joined;
+}
+const isWindows = process.platform === 'win32';
+/**
+ * Execute a filesystem operation with retry logic on Windows.
+ * On Windows, file operations can fail with EPERM/EBUSY/EACCES when files
+ * are briefly locked by another process or antivirus. This wrapper adds
+ * exponential backoff retry logic. On non-Windows platforms, executes directly.
+ */
+async function withWindowsRetry(fn, maxRetries = 5) {
+    if (!isWindows)
+        return fn();
+    const retryableErrors = ['EPERM', 'EBUSY', 'EACCES'];
+    const baseDelayMs = 10;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            const isRetryable = attempt < maxRetries && retryableErrors.includes(error.code);
+            if (!isRetryable)
+                throw error;
+            // Exponential backoff with jitter
+            const delay = baseDelayMs * 2 ** attempt + Math.random() * baseDelayMs;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+        }
+    }
+    // TypeScript: unreachable, but satisfies return type
+    throw new Error('Retry loop exited unexpectedly');
+}
+// In-memory cache of created files to avoid expensive fs.access() calls
+// This is safe because we only write once per file path (no overwrites without explicit flag)
+const createdFilesCache = new Set();
+/**
+ * Clear the created files cache. Useful for testing or when files are deleted externally.
+ */
+export function clearCreatedFilesCache() {
+    createdFilesCache.clear();
+}
+export { ulidToDate } from '@workflow/world';
+/**
+ * Regex matching a tag suffix on a fileId (after `.json` has been stripped).
+ * E.g., `wrun_ABC.vitest-0` → the `.vitest-0` part.
+ * Tags start with a letter and contain alphanumeric chars and hyphens.
+ * Entity IDs (ULIDs, step_N, etc.) never contain dots, so the first dot
+ * always marks the tag boundary.
+ */
+const TAG_PATTERN = /\.[a-zA-Z][a-zA-Z0-9-]*$/;
+/**
+ * Strip a tag suffix from a fileId.
+ * `wrun_ABC.vitest-0` → `wrun_ABC`
+ * `wrun_ABC` → `wrun_ABC` (no-op if no tag)
+ */
+export function stripTag(fileId) {
+    return fileId.replace(TAG_PATTERN, '');
+}
+/**
+ * Build the file path for an entity, with optional tag embedded in the filename.
+ * `taggedPath('/data', 'runs', 'wrun_ABC', 'vitest-0')` → `/data/runs/wrun_ABC.vitest-0.json`
+ * `taggedPath('/data', 'runs', 'wrun_ABC')` → `/data/runs/wrun_ABC.json`
+ *
+ * The `fileId` and `tag` are validated with {@link assertSafeEntityId} and
+ * the result is containment-checked with {@link resolveWithinBase} to
+ * prevent path-traversal attacks when values are derived from untrusted
+ * request input.
+ */
+export function taggedPath(basedir, entityDir, fileId, tag) {
+    assertSafeEntityId('fileId', fileId);
+    if (tag !== undefined)
+        assertSafeEntityId('tag', tag);
+    const filename = tag ? `${fileId}.${tag}.json` : `${fileId}.json`;
+    return resolveWithinBase(basedir, entityDir, filename);
+}
+/**
+ * Read a JSON entity with tagged fallback.
+ * When a tag is set, tries the tagged path first, then falls back to the
+ * untagged path (so a tagged world can read entities written without a tag).
+ */
+export async function readJSONWithFallback(basedir, entityDir, fileId, schema, tag) {
+    assertSafeEntityId('fileId', fileId);
+    if (tag !== undefined)
+        assertSafeEntityId('tag', tag);
+    if (tag) {
+        const result = await readJSON(resolveWithinBase(basedir, entityDir, `${fileId}.${tag}.json`), schema);
+        if (result !== null)
+            return result;
+    }
+    return readJSON(resolveWithinBase(basedir, entityDir, `${fileId}.json`), schema);
+}
+/**
+ * List all filenames in a directory that have a specific tag.
+ * Returns full filenames (e.g., `wrun_ABC.vitest-0.json`).
+ */
+export async function listTaggedFiles(dirPath, tag) {
+    const suffix = `.${tag}.json`;
+    try {
+        const files = await fs.readdir(dirPath);
+        return files.filter((f) => f.endsWith(suffix));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/**
+ * List all filenames in a directory that have a specific tag and extension.
+ * Returns full filenames (e.g., `stream-chnk_ABC.vitest-0.bin`).
+ */
+export async function listTaggedFilesByExtension(dirPath, tag, extension) {
+    const suffix = `.${tag}${extension}`;
+    try {
+        const files = await fs.readdir(dirPath);
+        return files.filter((f) => f.endsWith(suffix));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
     }
-    return new Date(decodeTime(ulid.data));
 }
 export async function ensureDir(dirPath) {
     try {
@@ -20,14 +200,56 @@ export async function ensureDir(dirPath) {
         // Ignore if already exists
     }
 }
+/**
+ * Custom JSON replacer that encodes Uint8Array as base64 strings.
+ * Format: { __type: 'Uint8Array', data: '<base64>' }
+ */
+export function jsonReplacer(_key, value) {
+    if (value instanceof Uint8Array) {
+        return {
+            __type: 'Uint8Array',
+            data: Buffer.from(value).toString('base64'),
+        };
+    }
+    return value;
+}
+/**
+ * Custom JSON reviver that decodes base64 strings back to Uint8Array.
+ */
+export function jsonReviver(_key, value) {
+    if (value !== null &&
+        typeof value === 'object' &&
+        value.__type === 'Uint8Array' &&
+        typeof value.data === 'string') {
+        return new Uint8Array(Buffer.from(value.data, 'base64'));
+    }
+    return value;
+}
 export async function writeJSON(filePath, data, opts) {
-    return write(filePath, JSON.stringify(data, null, 2), opts);
+    return write(filePath, JSON.stringify(data, jsonReplacer, 2), opts);
 }
+/**
+ * Writes data to a file using atomic write-rename pattern.
+ *
+ * Note: While this function uses temp files to avoid partial writes,
+ * it does not provide protection against concurrent writes from multiple
+ * processes. In a multi-writer scenario, the last writer wins.
+ * For production use with multiple writers, consider using a proper
+ * database or locking mechanism.
+ */
 export async function write(filePath, data, opts) {
     if (!opts?.overwrite) {
+        // Fast path: check in-memory cache first to avoid expensive fs.access() calls
+        // This provides significant performance improvement when creating many files
+        if (createdFilesCache.has(filePath)) {
+            throw new EntityConflictError(`File ${filePath} already exists and 'overwrite' is false`);
+        }
+        // Slow path: check filesystem for files created before this process started
         try {
             await fs.access(filePath);
-            throw new WorkflowAPIError(`File ${filePath} already exists and 'overwrite' is false`, { status: 409 });
+            // File exists on disk, add to cache for future checks
+            createdFilesCache.add(filePath);
+            throw new EntityConflictError(`File ${filePath} already exists and 'overwrite' is false`);
         }
         catch (error) {
             // If file doesn't exist (ENOENT), continue with write
@@ -37,20 +259,27 @@ export async function write(filePath, data, opts) {
         }
     }
     const tempPath = `${filePath}.tmp.${ulid()}`;
+    let tempFileCreated = false;
     try {
         await ensureDir(path.dirname(filePath));
         await fs.writeFile(tempPath, data);
-        await fs.rename(tempPath, filePath);
+        tempFileCreated = true;
+        await withWindowsRetry(() => fs.rename(tempPath, filePath));
+        // Track this file in cache so future writes know it exists
+        createdFilesCache.add(filePath);
     }
     catch (error) {
-        await fs.unlink(tempPath).catch(() => { });
+        // Only try to clean up temp file if it was actually created
+        if (tempFileCreated) {
+            await withWindowsRetry(() => fs.unlink(tempPath), 3).catch(() => { });
+        }
         throw error;
     }
 }
 export async function readJSON(filePath, decoder) {
     try {
         const content = await fs.readFile(filePath, 'utf-8');
-        return decoder.parse(JSON.parse(content));
+        return decoder.parse(JSON.parse(content, jsonReviver));
     }
     catch (error) {
         if (error.code === 'ENOENT')
@@ -71,12 +300,33 @@ export async function deleteJSON(filePath) {
             throw error;
     }
 }
+/**
+ * Atomically create a file using O_CREAT | O_EXCL flags.
+ * Returns true if the file was created, false if it already exists.
+ * This is atomic at the OS level, safe for concurrent access.
+ */
+export async function writeExclusive(filePath, data) {
+    await ensureDir(path.dirname(filePath));
+    try {
+        await fs.writeFile(filePath, data, { flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            return false;
+        }
+        throw error;
+    }
+}
 export async function listJSONFiles(dirPath) {
+    return listFilesByExtension(dirPath, '.json');
+}
+export async function listFilesByExtension(dirPath, extension) {
     try {
         const files = await fs.readdir(dirPath);
         return files
-            .filter((f) => f.endsWith('.json'))
-            .map((f) => f.replace('.json', ''));
+            .filter((f) => f.endsWith(extension))
+            .map((f) => f.slice(0, -extension.length));
     }
     catch (error) {
         if (error.code === 'ENOENT')
@@ -98,6 +348,14 @@ function createCursor(timestamp, id) {
 }
 export async function paginatedFileSystemQuery(config) {
     const { directory, schema, filePrefix, filter, sortOrder = 'desc', limit = 20, cursor, getCreatedAt, getId, } = config;
+    // Validate filePrefix (typically `${runId}-`) so request-derived prefixes
+    // consistently reject unsafe characters. filePrefix is only used below to
+    // filter readdir() results by prefix — it doesn't participate in path
+    // construction — but keeping the validation rule uniform across the
+    // storage layer avoids special cases and catches bad values earlier.
+    if (filePrefix !== undefined) {
+        assertSafeEntityId('filePrefix', filePrefix);
+    }
     // 1. Get all JSON files in directory
     const fileIds = await listJSONFiles(directory);
     // 2. Filter by prefix if provided
@@ -130,21 +388,30 @@ export async function paginatedFileSystemQuery(config) {
                         : fileTime > cursorTime;
                 }
             }
-            // Skip files where we can't extract timestamp - no optimization benefit
-            return false;
-        });
-    }
-    else {
-        // Even without cursor, skip files where getCreatedAt returns null for consistency
-        candidateFileIds = relevantFileIds.filter((fileId) => {
-            return getCreatedAt(`${fileId}.json`) !== null;
+            // Can't extract timestamp from filename (e.g., steps use sequential IDs).
+            // Include the file and defer to JSON-based filtering below.
+            return true;
         });
     }
     // 4. Load files individually and collect valid items
     const validItems = [];
     for (const fileId of candidateFileIds) {
         const filePath = path.join(directory, `${fileId}.json`);
-        const item = await readJSON(filePath, schema);
+        let item = null;
+        try {
+            item = await readJSON(filePath, schema);
+        }
+        catch (error) {
+            // We don't expect zod errors to happen, but if the JSON does get malformed,
+            // we skip the item. Preferably, we'd have a way to mark items as malformed,
+            // so that the UI can display them as such, with richer messaging. In the meantime,
+            // we just log a warning and skip the item.
+            if (error instanceof z.ZodError) {
+                console.warn(`Skipping item ${fileId} due to malformed JSON: ${error.message}`);
+                continue;
+            }
+            throw error;
+        }
         if (item) {
             // Apply custom filter early if provided
             if (filter && !filter(item))