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

package/dist/index.js

@@ -1,24 +1,101 @@
+import { promises as fs } from 'node:fs';
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';
 import { config } from './config.js';
+import { clearCreatedFilesCache, deleteJSON, listTaggedFiles, listTaggedFilesByExtension, readJSON, } from './fs.js';
+import { initDataDir } from './init.js';
+import { instrumentObject } from './instrumentObject.js';
 import { createQueue } from './queue.js';
+import { hashToken } from './storage/helpers.js';
 import { createStorage } from './storage.js';
 import { createStreamer } from './streamer.js';
+// Re-export init types and utilities for consumers
+export { DataDirAccessError, DataDirVersionError, ensureDataDir, initDataDir, parseVersion, } from './init.js';
 /**
- * Creates an embedded world instance that combines queue, storage, and streamer functionalities.
+ * Creates a local world instance that combines queue, storage, and streamer functionalities.
  *
  * @param args - Optional configuration object
  * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)
  * @param args.port - Port override for queue transport (default: auto-detected)
  * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)
+ * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written
+ *   as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.
+ * @throws {DataDirAccessError} If the data directory cannot be created or accessed
+ * @throws {DataDirVersionError} If the data directory version is incompatible
  */
-export function createEmbeddedWorld(args) {
+export function createLocalWorld(args) {
     const definedArgs = args
         ? Object.fromEntries(Object.entries(args).filter(([, value]) => value !== undefined))
         : {};
     const mergedConfig = { ...config.value, ...definedArgs };
+    const tag = mergedConfig.tag;
+    const queue = createQueue(mergedConfig);
+    const storage = createStorage(mergedConfig.dataDir, tag);
     return {
-        ...createQueue(mergedConfig),
-        ...createStorage(mergedConfig.dataDir),
-        ...createStreamer(mergedConfig.dataDir),
+        specVersion: SPEC_VERSION_CURRENT,
+        ...queue,
+        ...createStorage(mergedConfig.dataDir, tag),
+        ...instrumentObject('world.streams', {
+            ...createStreamer(mergedConfig.dataDir, tag),
+            ...(mergedConfig.streamFlushIntervalMs !== undefined && {
+                streamFlushIntervalMs: mergedConfig.streamFlushIntervalMs,
+            }),
+        }),
+        async start() {
+            await initDataDir(mergedConfig.dataDir);
+            await reenqueueActiveRuns(storage.runs, queue.queue, 'world-local');
+        },
+        async close() {
+            await queue.close();
+        },
+        async clear() {
+            if (tag) {
+                // Selectively delete only files matching this tag
+                const basedir = mergedConfig.dataDir;
+                // Delete hook token constraint files BEFORE deleting the hooks,
+                // since we need to read each hook to extract its token hash.
+                // Constraint files are untagged ({sha256}.json) so listTaggedFiles
+                // won't find them — we must resolve them via the hook data.
+                const hooksDir = path.join(basedir, 'hooks');
+                const taggedHookFiles = await listTaggedFiles(hooksDir, tag);
+                const { HookSchema } = await import('@workflow/world');
+                await Promise.all(taggedHookFiles.map(async (hookFile) => {
+                    const hook = await readJSON(path.join(hooksDir, hookFile), HookSchema);
+                    if (hook?.token) {
+                        await deleteJSON(path.join(hooksDir, 'tokens', `${hashToken(hook.token)}.json`));
+                    }
+                }));
+                // Delete tagged entity files across all directories
+                const entityDirs = [
+                    'runs',
+                    'steps',
+                    'events',
+                    'hooks',
+                    'waits',
+                    'streams/runs',
+                ];
+                await Promise.all(entityDirs.map(async (dir) => {
+                    const fullDir = path.join(basedir, dir);
+                    const files = await listTaggedFiles(fullDir, tag);
+                    await Promise.all(files.map((f) => deleteJSON(path.join(fullDir, f))));
+                }));
+                // Clean up lock files used for atomic terminal-state guards
+                await fs
+                    .rm(path.join(basedir, '.locks'), { recursive: true, force: true })
+                    .catch(() => { });
+                // Delete tagged stream chunks (.{tag}.bin files)
+                const chunksDir = path.join(basedir, 'streams', 'chunks');
+                const taggedBinFiles = await listTaggedFilesByExtension(chunksDir, tag, '.bin');
+                await Promise.all(taggedBinFiles.map((f) => fs.unlink(path.join(chunksDir, f)).catch(() => { })));
+                // Clear the in-memory write cache so deleted paths are forgotten
+                clearCreatedFilesCache();
+            }
+            else {
+                await rm(mergedConfig.dataDir, { recursive: true, force: true });
+                await initDataDir(mergedConfig.dataDir);
+            }
+        },
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAsB;IACxD,MAAM,WAAW,GAAG,IAAI;QACtB,CAAC,CAAC,MAAM,CAAC,WAAW,CAChB,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,SAAS,CAAC,CAChE;QACH,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,YAAY,GAAG,EAAE,GAAG,MAAM,CAAC,KAAK,EAAE,GAAG,WAAW,EAAE,CAAC;IACzD,OAAO;QACL,GAAG,WAAW,CAAC,YAAY,CAAC;QAC5B,GAAG,aAAa,CAAC,YAAY,CAAC,OAAO,CAAC;QACtC,GAAG,cAAc,CAAC,YAAY,CAAC,OAAO,CAAC;KACxC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { promises as fs } from 'node:fs';\nimport { rm } from 'node:fs/promises';\nimport path from 'node:path';\nimport type { World } from '@workflow/world';\nimport { reenqueueActiveRuns, SPEC_VERSION_CURRENT } from '@workflow/world';\nimport type { Config } from './config.js';\nimport { config } from './config.js';\nimport {\n  clearCreatedFilesCache,\n  deleteJSON,\n  listTaggedFiles,\n  listTaggedFilesByExtension,\n  readJSON,\n} from './fs.js';\nimport { initDataDir } from './init.js';\nimport { instrumentObject } from './instrumentObject.js';\nimport { createQueue, type DirectHandler } from './queue.js';\nimport { hashToken } from './storage/helpers.js';\nimport { createStorage } from './storage.js';\nimport { createStreamer } from './streamer.js';\n\n// Re-export init types and utilities for consumers\nexport {\n  DataDirAccessError,\n  DataDirVersionError,\n  ensureDataDir,\n  initDataDir,\n  type ParsedVersion,\n  parseVersion,\n} from './init.js';\n\nexport type { DirectHandler } from './queue.js';\n\nexport type LocalWorld = World & {\n  /** Register a direct in-process handler for a queue prefix, bypassing HTTP. */\n  registerHandler(\n    prefix: '__wkf_step_' | '__wkf_workflow_',\n    handler: DirectHandler\n  ): void;\n  /** Clear all workflow data (runs, steps, events, hooks, streams). */\n  clear(): Promise<void>;\n};\n\n/**\n * Creates a local world instance that combines queue, storage, and streamer functionalities.\n *\n * @param args - Optional configuration object\n * @param args.dataDir - Directory for storing workflow data (default: `.workflow-data/`)\n * @param args.port - Port override for queue transport (default: auto-detected)\n * @param args.baseUrl - Full base URL override for queue transport (default: `http://localhost:{port}`)\n * @param args.tag - Optional tag to scope files (e.g., `vitest-0`). When set, files are written\n *   as `{id}.{tag}.json` and `clear()` only deletes files matching this tag.\n * @throws {DataDirAccessError} If the data directory cannot be created or accessed\n * @throws {DataDirVersionError} If the data directory version is incompatible\n */\nexport function createLocalWorld(args?: Partial<Config>): LocalWorld {\n  const definedArgs = args\n    ? Object.fromEntries(\n        Object.entries(args).filter(([, value]) => value !== undefined)\n      )\n    : {};\n  const mergedConfig = { ...config.value, ...definedArgs };\n  const tag = mergedConfig.tag;\n  const queue = createQueue(mergedConfig);\n  const storage = createStorage(mergedConfig.dataDir, tag);\n  return {\n    specVersion: SPEC_VERSION_CURRENT,\n    ...queue,\n    ...createStorage(mergedConfig.dataDir, tag),\n    ...instrumentObject('world.streams', {\n      ...createStreamer(mergedConfig.dataDir, tag),\n      ...(mergedConfig.streamFlushIntervalMs !== undefined && {\n        streamFlushIntervalMs: mergedConfig.streamFlushIntervalMs,\n      }),\n    }),\n    async start() {\n      await initDataDir(mergedConfig.dataDir);\n      await reenqueueActiveRuns(storage.runs, queue.queue, 'world-local');\n    },\n    async close() {\n      await queue.close();\n    },\n    async clear() {\n      if (tag) {\n        // Selectively delete only files matching this tag\n        const basedir = mergedConfig.dataDir;\n\n        // Delete hook token constraint files BEFORE deleting the hooks,\n        // since we need to read each hook to extract its token hash.\n        // Constraint files are untagged ({sha256}.json) so listTaggedFiles\n        // won't find them — we must resolve them via the hook data.\n        const hooksDir = path.join(basedir, 'hooks');\n        const taggedHookFiles = await listTaggedFiles(hooksDir, tag);\n        const { HookSchema } = await import('@workflow/world');\n        await Promise.all(\n          taggedHookFiles.map(async (hookFile) => {\n            const hook = await readJSON(\n              path.join(hooksDir, hookFile),\n              HookSchema\n            );\n            if (hook?.token) {\n              await deleteJSON(\n                path.join(hooksDir, 'tokens', `${hashToken(hook.token)}.json`)\n              );\n            }\n          })\n        );\n\n        // Delete tagged entity files across all directories\n        const entityDirs = [\n          'runs',\n          'steps',\n          'events',\n          'hooks',\n          'waits',\n          'streams/runs',\n        ];\n        await Promise.all(\n          entityDirs.map(async (dir) => {\n            const fullDir = path.join(basedir, dir);\n            const files = await listTaggedFiles(fullDir, tag);\n            await Promise.all(\n              files.map((f) => deleteJSON(path.join(fullDir, f)))\n            );\n          })\n        );\n        // Clean up lock files used for atomic terminal-state guards\n        await fs\n          .rm(path.join(basedir, '.locks'), { recursive: true, force: true })\n          .catch(() => {});\n        // Delete tagged stream chunks (.{tag}.bin files)\n        const chunksDir = path.join(basedir, 'streams', 'chunks');\n        const taggedBinFiles = await listTaggedFilesByExtension(\n          chunksDir,\n          tag,\n          '.bin'\n        );\n        await Promise.all(\n          taggedBinFiles.map((f) =>\n            fs.unlink(path.join(chunksDir, f)).catch(() => {})\n          )\n        );\n        // Clear the in-memory write cache so deleted paths are forgotten\n        clearCreatedFilesCache();\n      } else {\n        await rm(mergedConfig.dataDir, { recursive: true, force: true });\n        await initDataDir(mergedConfig.dataDir);\n      }\n    },\n  };\n}\n"]}

package/dist/init.d.ts

@@ -0,0 +1,91 @@
+interface PackageInfo {
+    name: string;
+    version: string;
+}
+/**
+ * Returns the package name and version from package.json.
+ * The result is cached after the first read.
+ *
+ * In bundled contexts where package.json cannot be read,
+ * returns 'bundled' as the version.
+ */
+export declare function getPackageInfo(): Promise<PackageInfo>;
+/**
+ * Represents a parsed semantic version with optional prerelease tag.
+ */
+export interface ParsedVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+    raw: string;
+}
+/**
+ * Error thrown when the data directory cannot be accessed or created.
+ */
+export declare class DataDirAccessError extends Error {
+    readonly dataDir: string;
+    readonly code?: string;
+    constructor(message: string, dataDir: string, code?: string);
+}
+/**
+ * Error thrown when data directory version is incompatible.
+ */
+export declare class DataDirVersionError extends Error {
+    readonly oldVersion: ParsedVersion;
+    readonly newVersion: ParsedVersion;
+    readonly suggestedVersion?: string;
+    constructor(message: string, oldVersion: ParsedVersion, newVersion: ParsedVersion, suggestedVersion?: string);
+}
+/**
+ * Parses a version string into its components.
+ *
+ * @param versionString - Version string like "4.0.1" or "4.0.1-beta.20"
+ * @returns Parsed version object with major, minor, patch, and optional prerelease
+ */
+export declare function parseVersion(versionString: string): ParsedVersion;
+/**
+ * Formats a parsed version back to a string.
+ */
+export declare function formatVersion(version: ParsedVersion): string;
+/**
+ * Parses the version file content to extract package name and version.
+ *
+ * @param content - Content like "@workflow/world-local@4.0.1-beta.20"
+ * @returns Object with packageName and version
+ */
+export declare function parseVersionFile(content: string): {
+    packageName: string;
+    version: ParsedVersion;
+};
+/**
+ * Formats the version file content.
+ */
+export declare function formatVersionFile(packageName: string, version: ParsedVersion): string;
+/**
+ * Handles version upgrades between old and new versions.
+ * This function is called when the data directory was created with a different version.
+ *
+ * @param oldVersion - The version that created the data directory
+ * @param newVersion - The current package version
+ * @throws {DataDirVersionError} If the versions are incompatible
+ */
+export declare function upgradeVersion(oldVersion: ParsedVersion, newVersion: ParsedVersion): void;
+/**
+ * Ensures the data directory exists and is writable.
+ * Creates the directory if it doesn't exist.
+ *
+ * @param dataDir - The path to the data directory
+ * @throws {DataDirAccessError} If the directory cannot be created or accessed
+ */
+export declare function ensureDataDir(dataDir: string): Promise<void>;
+/**
+ * Initializes the data directory, ensuring it exists, is accessible,
+ * and handles version compatibility.
+ *
+ * @param dataDir - The path to the data directory
+ * @throws {DataDirAccessError} If the directory cannot be created or accessed
+ */
+export declare function initDataDir(dataDir: string): Promise<void>;
+export {};
+//# sourceMappingURL=init.d.ts.map

package/dist/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"AAcA,UAAU,WAAW;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAgBD;;;;;;GAMG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC,CAyB3D;AAKD;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM;CAM5D;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC;IACnC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;gBAGjC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,aAAa,EACzB,gBAAgB,CAAC,EAAE,MAAM;CAQ5B;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,aAAa,CAejE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAG5D;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,aAAa,CAAC;CACxB,CAeA;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,aAAa,GACrB,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,aAAa,EACzB,UAAU,EAAE,aAAa,GACxB,IAAI,CAIN;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDlE;AA4DD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDhE"}

package/dist/init.js

@@ -0,0 +1,268 @@
+import { access, constants, mkdir, readFile, unlink, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Package name - hardcoded since it doesn't change */
+const PACKAGE_NAME = '@workflow/world-local';
+let cachedPackageInfo = null;
+/**
+ * Get the directory path for this module.
+ * Works in ESM and falls back to a constant in CJS contexts (which shouldn't happen)
+ */
+function getModuleDir() {
+    // In bundled CJS contexts, import.meta.url may be undefined or empty
+    if (typeof import.meta.url === 'string' && import.meta.url) {
+        return path.dirname(fileURLToPath(import.meta.url));
+    }
+    return null;
+}
+/**
+ * Returns the package name and version from package.json.
+ * The result is cached after the first read.
+ *
+ * In bundled contexts where package.json cannot be read,
+ * returns 'bundled' as the version.
+ */
+export async function getPackageInfo() {
+    if (cachedPackageInfo) {
+        return cachedPackageInfo;
+    }
+    const moduleDir = getModuleDir();
+    if (moduleDir) {
+        try {
+            const content = await readFile(path.join(moduleDir, '../package.json'), 'utf-8');
+            cachedPackageInfo = JSON.parse(content);
+            return cachedPackageInfo;
+        }
+        catch {
+            // Fall through to bundled fallback
+        }
+    }
+    // Bundled context - package.json not accessible
+    cachedPackageInfo = {
+        name: PACKAGE_NAME,
+        version: 'bundled',
+    };
+    return cachedPackageInfo;
+}
+/** Filename for storing version information in the data directory */
+const VERSION_FILENAME = 'version.txt';
+/**
+ * Error thrown when the data directory cannot be accessed or created.
+ */
+export class DataDirAccessError extends Error {
+    dataDir;
+    code;
+    constructor(message, dataDir, code) {
+        super(message);
+        this.name = 'DataDirAccessError';
+        this.dataDir = dataDir;
+        this.code = code;
+    }
+}
+/**
+ * Error thrown when data directory version is incompatible.
+ */
+export class DataDirVersionError extends Error {
+    oldVersion;
+    newVersion;
+    suggestedVersion;
+    constructor(message, oldVersion, newVersion, suggestedVersion) {
+        super(message);
+        this.name = 'DataDirVersionError';
+        this.oldVersion = oldVersion;
+        this.newVersion = newVersion;
+        this.suggestedVersion = suggestedVersion;
+    }
+}
+/**
+ * Parses a version string into its components.
+ *
+ * @param versionString - Version string like "4.0.1" or "4.0.1-beta.20"
+ * @returns Parsed version object with major, minor, patch, and optional prerelease
+ */
+export function parseVersion(versionString) {
+    // Match: major.minor.patch with optional prerelease
+    const match = versionString.match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (!match) {
+        throw new Error(`Invalid version string: "${versionString}"`);
+    }
+    return {
+        major: parseInt(match[1], 10),
+        minor: parseInt(match[2], 10),
+        patch: parseInt(match[3], 10),
+        prerelease: match[4],
+        raw: versionString,
+    };
+}
+/**
+ * Formats a parsed version back to a string.
+ */
+export function formatVersion(version) {
+    const base = `${version.major}.${version.minor}.${version.patch}`;
+    return version.prerelease ? `${base}-${version.prerelease}` : base;
+}
+/**
+ * Parses the version file content to extract package name and version.
+ *
+ * @param content - Content like "@workflow/world-local@4.0.1-beta.20"
+ * @returns Object with packageName and version
+ */
+export function parseVersionFile(content) {
+    const trimmed = content.trim();
+    const lastAtIndex = trimmed.lastIndexOf('@');
+    if (lastAtIndex <= 0) {
+        throw new Error(`Invalid version file content: "${content}"`);
+    }
+    const packageName = trimmed.substring(0, lastAtIndex);
+    const versionString = trimmed.substring(lastAtIndex + 1);
+    return {
+        packageName,
+        version: parseVersion(versionString),
+    };
+}
+/**
+ * Formats the version file content.
+ */
+export function formatVersionFile(packageName, version) {
+    return `${packageName}@${formatVersion(version)}`;
+}
+/**
+ * Handles version upgrades between old and new versions.
+ * This function is called when the data directory was created with a different version.
+ *
+ * @param oldVersion - The version that created the data directory
+ * @param newVersion - The current package version
+ * @throws {DataDirVersionError} If the versions are incompatible
+ */
+export function upgradeVersion(oldVersion, newVersion) {
+    console.log(`[world-local] Upgrading from version ${formatVersion(oldVersion)} to ${formatVersion(newVersion)}`);
+}
+/**
+ * Ensures the data directory exists and is writable.
+ * Creates the directory if it doesn't exist.
+ *
+ * @param dataDir - The path to the data directory
+ * @throws {DataDirAccessError} If the directory cannot be created or accessed
+ */
+export async function ensureDataDir(dataDir) {
+    const absolutePath = path.resolve(dataDir);
+    // Try to create the directory if it doesn't exist
+    try {
+        await mkdir(absolutePath, { recursive: true });
+    }
+    catch (error) {
+        const nodeError = error;
+        // EEXIST is fine - directory already exists
+        if (nodeError.code !== 'EEXIST') {
+            throw new DataDirAccessError(`Failed to create data directory "${absolutePath}": ${nodeError.message}`, absolutePath, nodeError.code);
+        }
+    }
+    // Verify the directory is accessible (readable)
+    try {
+        await access(absolutePath, constants.R_OK);
+    }
+    catch (error) {
+        const nodeError = error;
+        throw new DataDirAccessError(`Data directory "${absolutePath}" is not readable: ${nodeError.message}`, absolutePath, nodeError.code);
+    }
+    // Verify the directory is writable by attempting to write a temp file
+    const testFile = path.join(absolutePath, `.workflow-write-test-${Date.now()}`);
+    try {
+        await writeFile(testFile, '');
+        // Clean up test file — ENOENT during cleanup is harmless (may race
+        // with another process performing the same check concurrently)
+        await unlink(testFile).catch((e) => {
+            if (e.code !== 'ENOENT')
+                throw e;
+        });
+    }
+    catch (error) {
+        const nodeError = error;
+        throw new DataDirAccessError(`Data directory "${absolutePath}" is not writable: ${nodeError.message}`, absolutePath, nodeError.code);
+    }
+}
+/**
+ * Reads the version from the data directory's version file.
+ *
+ * @param dataDir - Path to the data directory
+ * @returns The parsed version info, or null if the file doesn't exist
+ */
+async function readVersionFile(dataDir) {
+    const versionFilePath = path.join(path.resolve(dataDir), VERSION_FILENAME);
+    try {
+        const content = await readFile(versionFilePath, 'utf-8');
+        return parseVersionFile(content);
+    }
+    catch (error) {
+        const nodeError = error;
+        if (nodeError.code === 'ENOENT') {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Writes the current version to the data directory's version file.
+ *
+ * @param dataDir - Path to the data directory
+ * @param version - The version to write
+ */
+async function writeVersionFile(dataDir, version) {
+    const versionFilePath = path.join(path.resolve(dataDir), VERSION_FILENAME);
+    const packageInfo = await getPackageInfo();
+    const content = formatVersionFile(packageInfo.name, version);
+    await writeFile(versionFilePath, content);
+}
+/**
+ * Gets the suggested downgrade version based on the old version.
+ * If a specific version is suggested in the error, use that.
+ * Otherwise, suggest the previous minor version if patch is 0,
+ * or previous major version if minor is also 0.
+ */
+function getSuggestedDowngradeVersion(oldVersion, suggestedVersion) {
+    if (suggestedVersion) {
+        return suggestedVersion;
+    }
+    // Suggest the old version as the downgrade target
+    return formatVersion(oldVersion);
+}
+/**
+ * Initializes the data directory, ensuring it exists, is accessible,
+ * and handles version compatibility.
+ *
+ * @param dataDir - The path to the data directory
+ * @throws {DataDirAccessError} If the directory cannot be created or accessed
+ */
+export async function initDataDir(dataDir) {
+    // First ensure the directory exists and is accessible
+    await ensureDataDir(dataDir);
+    const packageInfo = await getPackageInfo();
+    const currentVersion = parseVersion(packageInfo.version);
+    // Read existing version file
+    const existingVersionInfo = await readVersionFile(dataDir);
+    if (existingVersionInfo === null) {
+        // New data directory - write the current version
+        await writeVersionFile(dataDir, currentVersion);
+        return;
+    }
+    const { version: oldVersion } = existingVersionInfo;
+    // Check if versions are the same (no upgrade needed)
+    if (formatVersion(oldVersion) === formatVersion(currentVersion)) {
+        return;
+    }
+    // Attempt upgrade
+    try {
+        upgradeVersion(oldVersion, currentVersion);
+        // Upgrade succeeded - write the new version
+        await writeVersionFile(dataDir, currentVersion);
+    }
+    catch (error) {
+        const suggestedVersion = error instanceof DataDirVersionError ? error.suggestedVersion : undefined;
+        const downgradeTarget = getSuggestedDowngradeVersion(oldVersion, suggestedVersion);
+        console.error(`[world-local] Failed to upgrade data directory from version ${formatVersion(oldVersion)} to ${formatVersion(currentVersion)}:`, error instanceof Error ? error.message : error);
+        console.error(`[world-local] Data is not compatible with the current version. ` +
+            `Please downgrade to ${packageInfo.name}@${downgradeTarget}`);
+        throw error;
+    }
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  access,\n  constants,\n  mkdir,\n  readFile,\n  unlink,\n  writeFile,\n} from 'node:fs/promises';\nimport path from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/** Package name - hardcoded since it doesn't change */\nconst PACKAGE_NAME = '@workflow/world-local';\n\ninterface PackageInfo {\n  name: string;\n  version: string;\n}\n\nlet cachedPackageInfo: PackageInfo | null = null;\n\n/**\n * Get the directory path for this module.\n * Works in ESM and falls back to a constant in CJS contexts (which shouldn't happen)\n */\nfunction getModuleDir(): string | null {\n  // In bundled CJS contexts, import.meta.url may be undefined or empty\n  if (typeof import.meta.url === 'string' && import.meta.url) {\n    return path.dirname(fileURLToPath(import.meta.url));\n  }\n  return null;\n}\n\n/**\n * Returns the package name and version from package.json.\n * The result is cached after the first read.\n *\n * In bundled contexts where package.json cannot be read,\n * returns 'bundled' as the version.\n */\nexport async function getPackageInfo(): Promise<PackageInfo> {\n  if (cachedPackageInfo) {\n    return cachedPackageInfo;\n  }\n\n  const moduleDir = getModuleDir();\n  if (moduleDir) {\n    try {\n      const content = await readFile(\n        path.join(moduleDir, '../package.json'),\n        'utf-8'\n      );\n      cachedPackageInfo = JSON.parse(content) as PackageInfo;\n      return cachedPackageInfo;\n    } catch {\n      // Fall through to bundled fallback\n    }\n  }\n\n  // Bundled context - package.json not accessible\n  cachedPackageInfo = {\n    name: PACKAGE_NAME,\n    version: 'bundled',\n  };\n  return cachedPackageInfo;\n}\n\n/** Filename for storing version information in the data directory */\nconst VERSION_FILENAME = 'version.txt';\n\n/**\n * Represents a parsed semantic version with optional prerelease tag.\n */\nexport interface ParsedVersion {\n  major: number;\n  minor: number;\n  patch: number;\n  prerelease?: string;\n  raw: string;\n}\n\n/**\n * Error thrown when the data directory cannot be accessed or created.\n */\nexport class DataDirAccessError extends Error {\n  readonly dataDir: string;\n  readonly code?: string;\n\n  constructor(message: string, dataDir: string, code?: string) {\n    super(message);\n    this.name = 'DataDirAccessError';\n    this.dataDir = dataDir;\n    this.code = code;\n  }\n}\n\n/**\n * Error thrown when data directory version is incompatible.\n */\nexport class DataDirVersionError extends Error {\n  readonly oldVersion: ParsedVersion;\n  readonly newVersion: ParsedVersion;\n  readonly suggestedVersion?: string;\n\n  constructor(\n    message: string,\n    oldVersion: ParsedVersion,\n    newVersion: ParsedVersion,\n    suggestedVersion?: string\n  ) {\n    super(message);\n    this.name = 'DataDirVersionError';\n    this.oldVersion = oldVersion;\n    this.newVersion = newVersion;\n    this.suggestedVersion = suggestedVersion;\n  }\n}\n\n/**\n * Parses a version string into its components.\n *\n * @param versionString - Version string like \"4.0.1\" or \"4.0.1-beta.20\"\n * @returns Parsed version object with major, minor, patch, and optional prerelease\n */\nexport function parseVersion(versionString: string): ParsedVersion {\n  // Match: major.minor.patch with optional prerelease\n  const match = versionString.match(/^(\\d+)\\.(\\d+)\\.(\\d+)(?:-(.+))?$/);\n\n  if (!match) {\n    throw new Error(`Invalid version string: \"${versionString}\"`);\n  }\n\n  return {\n    major: parseInt(match[1], 10),\n    minor: parseInt(match[2], 10),\n    patch: parseInt(match[3], 10),\n    prerelease: match[4],\n    raw: versionString,\n  };\n}\n\n/**\n * Formats a parsed version back to a string.\n */\nexport function formatVersion(version: ParsedVersion): string {\n  const base = `${version.major}.${version.minor}.${version.patch}`;\n  return version.prerelease ? `${base}-${version.prerelease}` : base;\n}\n\n/**\n * Parses the version file content to extract package name and version.\n *\n * @param content - Content like \"@workflow/world-local@4.0.1-beta.20\"\n * @returns Object with packageName and version\n */\nexport function parseVersionFile(content: string): {\n  packageName: string;\n  version: ParsedVersion;\n} {\n  const trimmed = content.trim();\n  const lastAtIndex = trimmed.lastIndexOf('@');\n\n  if (lastAtIndex <= 0) {\n    throw new Error(`Invalid version file content: \"${content}\"`);\n  }\n\n  const packageName = trimmed.substring(0, lastAtIndex);\n  const versionString = trimmed.substring(lastAtIndex + 1);\n\n  return {\n    packageName,\n    version: parseVersion(versionString),\n  };\n}\n\n/**\n * Formats the version file content.\n */\nexport function formatVersionFile(\n  packageName: string,\n  version: ParsedVersion\n): string {\n  return `${packageName}@${formatVersion(version)}`;\n}\n\n/**\n * Handles version upgrades between old and new versions.\n * This function is called when the data directory was created with a different version.\n *\n * @param oldVersion - The version that created the data directory\n * @param newVersion - The current package version\n * @throws {DataDirVersionError} If the versions are incompatible\n */\nexport function upgradeVersion(\n  oldVersion: ParsedVersion,\n  newVersion: ParsedVersion\n): void {\n  console.log(\n    `[world-local] Upgrading from version ${formatVersion(oldVersion)} to ${formatVersion(newVersion)}`\n  );\n}\n\n/**\n * Ensures the data directory exists and is writable.\n * Creates the directory if it doesn't exist.\n *\n * @param dataDir - The path to the data directory\n * @throws {DataDirAccessError} If the directory cannot be created or accessed\n */\nexport async function ensureDataDir(dataDir: string): Promise<void> {\n  const absolutePath = path.resolve(dataDir);\n\n  // Try to create the directory if it doesn't exist\n  try {\n    await mkdir(absolutePath, { recursive: true });\n  } catch (error: unknown) {\n    const nodeError = error as NodeJS.ErrnoException;\n    // EEXIST is fine - directory already exists\n    if (nodeError.code !== 'EEXIST') {\n      throw new DataDirAccessError(\n        `Failed to create data directory \"${absolutePath}\": ${nodeError.message}`,\n        absolutePath,\n        nodeError.code\n      );\n    }\n  }\n\n  // Verify the directory is accessible (readable)\n  try {\n    await access(absolutePath, constants.R_OK);\n  } catch (error: unknown) {\n    const nodeError = error as NodeJS.ErrnoException;\n    throw new DataDirAccessError(\n      `Data directory \"${absolutePath}\" is not readable: ${nodeError.message}`,\n      absolutePath,\n      nodeError.code\n    );\n  }\n\n  // Verify the directory is writable by attempting to write a temp file\n  const testFile = path.join(\n    absolutePath,\n    `.workflow-write-test-${Date.now()}`\n  );\n  try {\n    await writeFile(testFile, '');\n    // Clean up test file — ENOENT during cleanup is harmless (may race\n    // with another process performing the same check concurrently)\n    await unlink(testFile).catch((e: NodeJS.ErrnoException) => {\n      if (e.code !== 'ENOENT') throw e;\n    });\n  } catch (error: unknown) {\n    const nodeError = error as NodeJS.ErrnoException;\n    throw new DataDirAccessError(\n      `Data directory \"${absolutePath}\" is not writable: ${nodeError.message}`,\n      absolutePath,\n      nodeError.code\n    );\n  }\n}\n\n/**\n * Reads the version from the data directory's version file.\n *\n * @param dataDir - Path to the data directory\n * @returns The parsed version info, or null if the file doesn't exist\n */\nasync function readVersionFile(dataDir: string): Promise<{\n  packageName: string;\n  version: ParsedVersion;\n} | null> {\n  const versionFilePath = path.join(path.resolve(dataDir), VERSION_FILENAME);\n\n  try {\n    const content = await readFile(versionFilePath, 'utf-8');\n    return parseVersionFile(content);\n  } catch (error: unknown) {\n    const nodeError = error as NodeJS.ErrnoException;\n    if (nodeError.code === 'ENOENT') {\n      return null;\n    }\n    throw error;\n  }\n}\n\n/**\n * Writes the current version to the data directory's version file.\n *\n * @param dataDir - Path to the data directory\n * @param version - The version to write\n */\nasync function writeVersionFile(\n  dataDir: string,\n  version: ParsedVersion\n): Promise<void> {\n  const versionFilePath = path.join(path.resolve(dataDir), VERSION_FILENAME);\n  const packageInfo = await getPackageInfo();\n  const content = formatVersionFile(packageInfo.name, version);\n  await writeFile(versionFilePath, content);\n}\n\n/**\n * Gets the suggested downgrade version based on the old version.\n * If a specific version is suggested in the error, use that.\n * Otherwise, suggest the previous minor version if patch is 0,\n * or previous major version if minor is also 0.\n */\nfunction getSuggestedDowngradeVersion(\n  oldVersion: ParsedVersion,\n  suggestedVersion?: string\n): string {\n  if (suggestedVersion) {\n    return suggestedVersion;\n  }\n\n  // Suggest the old version as the downgrade target\n  return formatVersion(oldVersion);\n}\n\n/**\n * Initializes the data directory, ensuring it exists, is accessible,\n * and handles version compatibility.\n *\n * @param dataDir - The path to the data directory\n * @throws {DataDirAccessError} If the directory cannot be created or accessed\n */\nexport async function initDataDir(dataDir: string): Promise<void> {\n  // First ensure the directory exists and is accessible\n  await ensureDataDir(dataDir);\n\n  const packageInfo = await getPackageInfo();\n  const currentVersion = parseVersion(packageInfo.version);\n\n  // Read existing version file\n  const existingVersionInfo = await readVersionFile(dataDir);\n\n  if (existingVersionInfo === null) {\n    // New data directory - write the current version\n    await writeVersionFile(dataDir, currentVersion);\n    return;\n  }\n\n  const { version: oldVersion } = existingVersionInfo;\n\n  // Check if versions are the same (no upgrade needed)\n  if (formatVersion(oldVersion) === formatVersion(currentVersion)) {\n    return;\n  }\n\n  // Attempt upgrade\n  try {\n    upgradeVersion(oldVersion, currentVersion);\n    // Upgrade succeeded - write the new version\n    await writeVersionFile(dataDir, currentVersion);\n  } catch (error: unknown) {\n    const suggestedVersion =\n      error instanceof DataDirVersionError ? error.suggestedVersion : undefined;\n\n    const downgradeTarget = getSuggestedDowngradeVersion(\n      oldVersion,\n      suggestedVersion\n    );\n\n    console.error(\n      `[world-local] Failed to upgrade data directory from version ${formatVersion(oldVersion)} to ${formatVersion(currentVersion)}:`,\n      error instanceof Error ? error.message : error\n    );\n    console.error(\n      `[world-local] Data is not compatible with the current version. ` +\n        `Please downgrade to ${packageInfo.name}@${downgradeTarget}`\n    );\n\n    throw error;\n  }\n}\n"]}

package/dist/instrumentObject.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Wraps all methods of an object with tracing spans.
+ * @param prefix - Prefix for span names (e.g., "world.runs")
+ * @param o - Object with methods to instrument
+ * @returns Instrumented object with same interface
+ */
+export declare function instrumentObject<T extends object>(prefix: string, o: T): T;
+//# sourceMappingURL=instrumentObject.d.ts.map

package/dist/instrumentObject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentObject.d.ts","sourceRoot":"","sources":["../src/instrumentObject.ts"],"names":[],"mappings":"AAkCA;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,GAAG,CAAC,CAsC1E"}

package/dist/instrumentObject.js

@@ -0,0 +1,66 @@
+/**
+ * Utility to instrument object methods with tracing.
+ * This mirrors world-vercel's implementation for consistent observability.
+ */
+import { trace, getSpanKind, PeerService, RpcSystem, RpcService, RpcMethod, } from './telemetry.js';
+/** Configuration for peer service attribution */
+const WORLD_LOCAL_SERVICE = {
+    peerService: 'world-local',
+    rpcSystem: 'local',
+    rpcService: 'world-local',
+};
+/**
+ * Extracts the event type from arguments for events.create calls.
+ * The event data is the second argument and contains eventType.
+ */
+function extractEventType(args) {
+    if (args.length >= 2 && typeof args[1] === 'object' && args[1] !== null) {
+        const data = args[1];
+        if (typeof data.eventType === 'string') {
+            return data.eventType;
+        }
+    }
+    return undefined;
+}
+/**
+ * Wraps all methods of an object with tracing spans.
+ * @param prefix - Prefix for span names (e.g., "world.runs")
+ * @param o - Object with methods to instrument
+ * @returns Instrumented object with same interface
+ */
+export function instrumentObject(prefix, o) {
+    const handlers = {};
+    for (const key of Object.keys(o)) {
+        if (typeof o[key] !== 'function') {
+            handlers[key] = o[key];
+        }
+        else {
+            const f = o[key];
+            const methodName = String(key);
+            // @ts-expect-error - dynamic function wrapping
+            handlers[key] = async (...args) => {
+                // Build span name - for events.create, include the event type
+                let spanName = `${prefix}.${methodName}`;
+                if (prefix === 'world.events' && methodName === 'create') {
+                    const eventType = extractEventType(args);
+                    if (eventType) {
+                        spanName = `${prefix}.${methodName} ${eventType}`;
+                    }
+                }
+                return trace(spanName, { kind: await getSpanKind('INTERNAL') }, async (span) => {
+                    // Add peer service attributes for service maps
+                    // Use spanName for rpc.method so Datadog shows event type in resource
+                    span?.setAttributes({
+                        ...PeerService(WORLD_LOCAL_SERVICE.peerService),
+                        ...RpcSystem(WORLD_LOCAL_SERVICE.rpcSystem),
+                        ...RpcService(WORLD_LOCAL_SERVICE.rpcService),
+                        ...RpcMethod(spanName),
+                    });
+                    return f(...args);
+                });
+            };
+        }
+    }
+    return handlers;
+}
+//# sourceMappingURL=instrumentObject.js.map

package/dist/instrumentObject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentObject.js","sourceRoot":"","sources":["../src/instrumentObject.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EACL,KAAK,EACL,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACV,SAAS,GACV,MAAM,gBAAgB,CAAC;AAExB,iDAAiD;AACjD,MAAM,mBAAmB,GAAG;IAC1B,WAAW,EAAE,aAAa;IAC1B,SAAS,EAAE,OAAO;IAClB,UAAU,EAAE,aAAa;CAC1B,CAAC;AAEF;;;GAGG;AACH,SAAS,gBAAgB,CAAC,IAAe;IACvC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QACxE,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,CAA4B,CAAC;QAChD,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;YACvC,OAAO,IAAI,CAAC,SAAS,CAAC;QACxB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAmB,MAAc,EAAE,CAAI;IACrE,MAAM,QAAQ,GAAG,EAAO,CAAC;IACzB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAgB,EAAE,CAAC;QAChD,IAAI,OAAO,CAAC,CAAC,GAAG,CAAC,KAAK,UAAU,EAAE,CAAC;YACjC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;YACjB,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YAC/B,+CAA+C;YAC/C,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,GAAG,IAAe,EAAE,EAAE;gBAC3C,8DAA8D;gBAC9D,IAAI,QAAQ,GAAG,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC;gBACzC,IAAI,MAAM,KAAK,cAAc,IAAI,UAAU,KAAK,QAAQ,EAAE,CAAC;oBACzD,MAAM,SAAS,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;oBACzC,IAAI,SAAS,EAAE,CAAC;wBACd,QAAQ,GAAG,GAAG,MAAM,IAAI,UAAU,IAAI,SAAS,EAAE,CAAC;oBACpD,CAAC;gBACH,CAAC;gBAED,OAAO,KAAK,CACV,QAAQ,EACR,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC,UAAU,CAAC,EAAE,EACvC,KAAK,EAAE,IAAI,EAAE,EAAE;oBACb,+CAA+C;oBAC/C,sEAAsE;oBACtE,IAAI,EAAE,aAAa,CAAC;wBAClB,GAAG,WAAW,CAAC,mBAAmB,CAAC,WAAW,CAAC;wBAC/C,GAAG,SAAS,CAAC,mBAAmB,CAAC,SAAS,CAAC;wBAC3C,GAAG,UAAU,CAAC,mBAAmB,CAAC,UAAU,CAAC;wBAC7C,GAAG,SAAS,CAAC,QAAQ,CAAC;qBACvB,CAAC,CAAC;oBACH,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBACpB,CAAC,CACF,CAAC;YACJ,CAAC,CAAC;QACJ,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * Utility to instrument object methods with tracing.\n * This mirrors world-vercel's implementation for consistent observability.\n */\nimport {\n  trace,\n  getSpanKind,\n  PeerService,\n  RpcSystem,\n  RpcService,\n  RpcMethod,\n} from './telemetry.js';\n\n/** Configuration for peer service attribution */\nconst WORLD_LOCAL_SERVICE = {\n  peerService: 'world-local',\n  rpcSystem: 'local',\n  rpcService: 'world-local',\n};\n\n/**\n * Extracts the event type from arguments for events.create calls.\n * The event data is the second argument and contains eventType.\n */\nfunction extractEventType(args: unknown[]): string | undefined {\n  if (args.length >= 2 && typeof args[1] === 'object' && args[1] !== null) {\n    const data = args[1] as Record<string, unknown>;\n    if (typeof data.eventType === 'string') {\n      return data.eventType;\n    }\n  }\n  return undefined;\n}\n\n/**\n * Wraps all methods of an object with tracing spans.\n * @param prefix - Prefix for span names (e.g., \"world.runs\")\n * @param o - Object with methods to instrument\n * @returns Instrumented object with same interface\n */\nexport function instrumentObject<T extends object>(prefix: string, o: T): T {\n  const handlers = {} as T;\n  for (const key of Object.keys(o) as (keyof T)[]) {\n    if (typeof o[key] !== 'function') {\n      handlers[key] = o[key];\n    } else {\n      const f = o[key];\n      const methodName = String(key);\n      // @ts-expect-error - dynamic function wrapping\n      handlers[key] = async (...args: unknown[]) => {\n        // Build span name - for events.create, include the event type\n        let spanName = `${prefix}.${methodName}`;\n        if (prefix === 'world.events' && methodName === 'create') {\n          const eventType = extractEventType(args);\n          if (eventType) {\n            spanName = `${prefix}.${methodName} ${eventType}`;\n          }\n        }\n\n        return trace(\n          spanName,\n          { kind: await getSpanKind('INTERNAL') },\n          async (span) => {\n            // Add peer service attributes for service maps\n            // Use spanName for rpc.method so Datadog shows event type in resource\n            span?.setAttributes({\n              ...PeerService(WORLD_LOCAL_SERVICE.peerService),\n              ...RpcSystem(WORLD_LOCAL_SERVICE.rpcSystem),\n              ...RpcService(WORLD_LOCAL_SERVICE.rpcService),\n              ...RpcMethod(spanName),\n            });\n            return f(...args);\n          }\n        );\n      };\n    }\n  }\n  return handlers;\n}\n"]}

package/dist/queue.d.ts

@@ -1,4 +1,11 @@
 import { type Queue } from '@workflow/world';
 import type { Config } from './config.js';
-export declare function createQueue(config: Partial<Config>): Queue;
+export type DirectHandler = (req: Request) => Promise<Response>;
+export type LocalQueue = Queue & {
+    /** Close the HTTP agent and release resources. */
+    close(): Promise<void>;
+    /** Register a direct in-process handler for a queue prefix, bypassing HTTP. */
+    registerHandler(prefix: '__wkf_step_' | '__wkf_workflow_', handler: DirectHandler): void;
+};
+export declare function createQueue(config: Partial<Config>): LocalQueue;
 //# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,KAAK,EAAkB,MAAM,iBAAiB,CAAC;AAIxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAc1C,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,CA2J1D"}
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAEA,OAAO,EAAa,KAAK,KAAK,EAAkB,MAAM,iBAAiB,CAAC;AAKxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAiD1C,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhE,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG;IAC/B,kDAAkD;IAClD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,+EAA+E;IAC/E,eAAe,CACb,MAAM,EAAE,aAAa,GAAG,iBAAiB,EACzC,OAAO,EAAE,aAAa,GACrB,IAAI,CAAC;CACT,CAAC;AAeF,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,UAAU,CAoP/D"}