@lumenflow/core 3.1.2 → 3.2.0

package/dist/spawn-recovery.js

@@ -1,299 +0,0 @@
-/**
- * Spawn Recovery Module (WU-1951)
- *
- * Auto-recovery heuristics for stuck spawns and zombie locks.
- * Used by orchestrate:monitor for automatic spawn health management.
- *
- * Recovery Heuristics:
- * 1. Zombie lock (PID not running) -> auto-release, mark spawn crashed
- * 2. Stale lock (>2h) -> auto-release, mark spawn timeout
- * 3. Active lock + no checkpoint in 1h -> mark stuck, escalate
- *
- * All recovery actions are logged to .lumenflow/recovery/ for audit.
- *
- * Library-First Note: This is project-specific spawn recovery code for
- * PatientPath's custom spawn-registry.jsonl, lane-lock, and memory-store.
- * No external library exists for this domain-specific agent lifecycle management.
- *
- * @see {@link packages/@lumenflow/cli/src/lib/__tests__/spawn-recovery.test.ts} - Tests
- * @see {@link packages/@lumenflow/cli/src/lib/spawn-monitor.ts} - Monitoring logic
- * @see {@link packages/@lumenflow/cli/src/lib/spawn-registry-store.ts} - Spawn state
- */
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { SpawnRegistryStore } from './spawn-registry-store.js';
-import { SpawnStatus } from './spawn-registry-schema.js';
-import { isZombieLock, isLockStale, readLockMetadata, getLockFilePath, releaseLaneLock, } from './lane-lock.js';
-import { toKebab, LUMENFLOW_PATHS } from './wu-constants.js';
-// Optional import from @lumenflow/memory
-let loadMemory = null;
-try {
-    const mod = await import('@lumenflow/memory/store');
-    loadMemory = mod.loadMemory;
-}
-catch {
-    // @lumenflow/memory not available - memory features disabled
-}
-/**
- * Recovery action constants
- */
-export const RecoveryAction = Object.freeze({
-    /** No recovery needed */
-    NONE: 'none',
-    /** Zombie lock released (PID not running) */
-    RELEASED_ZOMBIE: 'released_zombie',
-    /** Stale lock released (>2h old) */
-    RELEASED_STALE: 'released_stale',
-    /** Stuck spawn escalated (active but no checkpoint in 1h) */
-    ESCALATED_STUCK: 'escalated_stuck',
-});
-/**
- * Recovery directory name
- */
-export const RECOVERY_DIR_NAME = 'recovery';
-/**
- * Threshold for "no checkpoint" detection (1 hour in milliseconds)
- */
-export const NO_CHECKPOINT_THRESHOLD_MS = 60 * 60 * 1000;
-/**
- * Log prefix for spawn-recovery messages
- */
-const LOG_PREFIX = '[spawn-recovery]';
-/**
- * @typedef {Object} RecoveryResult
- * @property {boolean} recovered - Whether a recovery action was taken
- * @property {string} action - The recovery action taken (from RecoveryAction)
- * @property {string} reason - Human-readable explanation of the result
- */
-/**
- * @typedef {Object} AuditLogEntry
- * @property {string} timestamp - ISO timestamp of recovery action
- * @property {string} spawnId - ID of the spawn being recovered
- * @property {string} action - Recovery action taken
- * @property {string} reason - Explanation of why action was taken
- * @property {Object} context - Additional context
- * @property {string} context.targetWuId - Target WU ID
- * @property {string} context.lane - Lane name
- * @property {Object|null} context.lockMetadata - Lock metadata if present
- * @property {string|null} context.lastCheckpoint - Last checkpoint timestamp
- */
-/**
- * Converts lane name to lock file path (kebab-case)
- *
- * @param {string} lane - Lane name (e.g., "Operations: Tooling")
- * @returns {string} Kebab-case lane name (e.g., "operations-tooling")
- */
-function laneToKebab(lane) {
-    return toKebab(lane);
-}
-/**
- * Gets the recovery directory path
- *
- * @param {string} baseDir - Base directory
- * @returns {string} Path to .lumenflow/recovery/
- */
-function getRecoveryDir(baseDir) {
-    return path.join(baseDir, LUMENFLOW_PATHS.BASE, RECOVERY_DIR_NAME);
-}
-/**
- * Creates an audit log entry
- *
- * @param {string} baseDir - Base directory
- * @param {AuditLogEntry} entry - Audit log entry
- * @returns {Promise<void>}
- */
-async function createAuditLog(baseDir, entry) {
-    const recoveryDir = getRecoveryDir(baseDir);
-    await fs.mkdir(recoveryDir, { recursive: true });
-    const timestamp = entry.timestamp.replace(/[:.]/g, '-');
-    const fileName = `${entry.spawnId}-${timestamp}.json`;
-    const filePath = path.join(recoveryDir, fileName);
-    await fs.writeFile(filePath, JSON.stringify(entry, null, 2), 'utf-8');
-    console.log(`${LOG_PREFIX} Audit log created: ${fileName}`);
-}
-/**
- * Gets the most recent checkpoint for a WU from the memory store
- *
- * @param {string} baseDir - Base directory
- * @param {string} wuId - WU ID to find checkpoints for
- * @returns {Promise<{timestamp: string, content: string}|null>} Most recent checkpoint or null
- */
-async function getLastCheckpoint(baseDir, wuId) {
-    // If memory module not available, return null
-    if (!loadMemory) {
-        return null;
-    }
-    const memoryDir = path.join(baseDir, LUMENFLOW_PATHS.STATE_DIR);
-    try {
-        const memory = await loadMemory(memoryDir, wuId);
-        if (!memory) {
-            return null;
-        }
-        const checkpoints = memory.checkpoints ?? [];
-        if (checkpoints.length === 0) {
-            return null;
-        }
-        // Sort by timestamp descending, get most recent
-        checkpoints.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
-        const latest = checkpoints[0];
-        return {
-            timestamp: latest.timestamp,
-            content: '',
-        };
-    }
-    catch {
-        // Memory store doesn't exist or is invalid
-        return null;
-    }
-}
-/**
- * Checks if a checkpoint is recent enough (within 1 hour)
- *
- * @param {string|null} checkpointTimestamp - ISO timestamp of last checkpoint
- * @returns {boolean} True if checkpoint is recent (within 1 hour)
- */
-function isCheckpointRecent(checkpointTimestamp) {
-    if (!checkpointTimestamp) {
-        return false;
-    }
-    const checkpointTime = new Date(checkpointTimestamp).getTime();
-    const now = Date.now();
-    return now - checkpointTime <= NO_CHECKPOINT_THRESHOLD_MS;
-}
-export async function recoverStuckSpawn(spawnId, options = {}) {
-    const { baseDir = process.cwd() } = options;
-    const registryDir = path.join(baseDir, LUMENFLOW_PATHS.STATE_DIR);
-    // Load spawn registry
-    const store = new SpawnRegistryStore(registryDir);
-    try {
-        await store.load();
-    }
-    catch {
-        // Registry doesn't exist or is invalid
-        return {
-            recovered: false,
-            action: RecoveryAction.NONE,
-            reason: `Spawn ${spawnId} not found: registry unavailable`,
-        };
-    }
-    // Find the spawn
-    const spawn = store.getById(spawnId);
-    if (!spawn) {
-        return {
-            recovered: false,
-            action: RecoveryAction.NONE,
-            reason: `Spawn ${spawnId} not found in registry`,
-        };
-    }
-    // Check if already completed
-    if (spawn.status !== SpawnStatus.PENDING) {
-        return {
-            recovered: false,
-            action: RecoveryAction.NONE,
-            reason: `Spawn ${spawnId} already ${spawn.status}`,
-        };
-    }
-    // Get lock for this spawn's lane
-    const _laneKebab = laneToKebab(spawn.lane);
-    const lockPath = getLockFilePath(spawn.lane, baseDir);
-    const lockMetadata = readLockMetadata(lockPath);
-    // If no lock, nothing to recover
-    if (!lockMetadata) {
-        return {
-            recovered: false,
-            action: RecoveryAction.NONE,
-            reason: `No lock found for spawn ${spawnId} (lane: ${spawn.lane})`,
-        };
-    }
-    // Check if lock belongs to this WU
-    if (lockMetadata.wuId !== spawn.targetWuId) {
-        return {
-            recovered: false,
-            action: RecoveryAction.NONE,
-            reason: `Lock belongs to ${lockMetadata.wuId}, not spawn target ${spawn.targetWuId}`,
-        };
-    }
-    // Get last checkpoint for context
-    const lastCheckpoint = await getLastCheckpoint(baseDir, spawn.targetWuId);
-    const lastCheckpointTs = lastCheckpoint?.timestamp ?? null;
-    // Build common audit context
-    const auditContext = {
-        targetWuId: spawn.targetWuId,
-        parentWuId: spawn.parentWuId,
-        lane: spawn.lane,
-        spawnedAt: spawn.spawnedAt,
-        lockMetadata,
-        lastCheckpoint: lastCheckpointTs,
-    };
-    // Heuristic 1: Zombie lock (PID not running)
-    if (isZombieLock(lockMetadata)) {
-        console.log(`${LOG_PREFIX} Detected zombie lock for ${spawnId} (PID ${lockMetadata.pid} not running)`);
-        // Release the lock
-        releaseLaneLock(spawn.lane, { baseDir, force: true });
-        // Mark spawn as crashed
-        await store.updateStatus(spawnId, SpawnStatus.CRASHED);
-        const reason = `Zombie lock detected: PID ${lockMetadata.pid} not running`;
-        // Create audit log
-        await createAuditLog(baseDir, {
-            timestamp: new Date().toISOString(),
-            spawnId,
-            action: RecoveryAction.RELEASED_ZOMBIE,
-            reason,
-            context: auditContext,
-        });
-        return {
-            recovered: true,
-            action: RecoveryAction.RELEASED_ZOMBIE,
-            reason,
-        };
-    }
-    // Heuristic 2: Stale lock (>2h old)
-    if (isLockStale(lockMetadata)) {
-        console.log(`${LOG_PREFIX} Detected stale lock for ${spawnId} (acquired ${lockMetadata.timestamp})`);
-        // Release the lock
-        releaseLaneLock(spawn.lane, { baseDir, force: true });
-        // Mark spawn as timeout
-        await store.updateStatus(spawnId, SpawnStatus.TIMEOUT);
-        const reason = `Stale lock detected: acquired ${lockMetadata.timestamp} (>2h threshold)`;
-        // Create audit log
-        await createAuditLog(baseDir, {
-            timestamp: new Date().toISOString(),
-            spawnId,
-            action: RecoveryAction.RELEASED_STALE,
-            reason,
-            context: auditContext,
-        });
-        return {
-            recovered: true,
-            action: RecoveryAction.RELEASED_STALE,
-            reason,
-        };
-    }
-    // Heuristic 3: Active lock + no recent checkpoint -> escalate
-    if (!isCheckpointRecent(lastCheckpointTs)) {
-        const reason = lastCheckpointTs
-            ? `No checkpoint in last hour (last: ${lastCheckpointTs})`
-            : 'No checkpoints recorded for this spawn';
-        console.log(`${LOG_PREFIX} Escalating stuck spawn ${spawnId}: ${reason}`);
-        // Create audit log (escalation, not recovery)
-        await createAuditLog(baseDir, {
-            timestamp: new Date().toISOString(),
-            spawnId,
-            action: RecoveryAction.ESCALATED_STUCK,
-            reason,
-            context: auditContext,
-        });
-        return {
-            recovered: false, // No auto-recovery, just escalation
-            action: RecoveryAction.ESCALATED_STUCK,
-            reason: `Stuck spawn: ${reason}`,
-        };
-    }
-    // Healthy spawn with recent checkpoint
-    return {
-        recovered: false,
-        action: RecoveryAction.NONE,
-        reason: `Spawn ${spawnId} healthy (recent checkpoint at ${lastCheckpointTs})`,
-    };
-}
-//# sourceMappingURL=spawn-recovery.js.map

package/dist/spawn-recovery.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"spawn-recovery.js","sourceRoot":"","sources":["../src/spawn-recovery.ts"],"names":[],"mappings":"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"}

package/dist/spawn-registry-schema.d.ts

@@ -1,122 +0,0 @@
-/**
- * Spawn Registry Schema (WU-1944)
- *
- * Zod schemas for spawn event validation.
- * Defines schema for tracking sub-agent spawns by orchestrators.
- *
- * @see {@link packages/@lumenflow/cli/src/lib/__tests__/spawn-registry-store.test.ts} - Tests
- * @see {@link packages/@lumenflow/cli/src/lib/spawn-registry-store.ts} - Store implementation
- */
-import { z } from 'zod';
-/**
- * Spawn status values
- */
-export declare const SpawnStatus: {
-    readonly PENDING: "pending";
-    readonly COMPLETED: "completed";
-    readonly TIMEOUT: "timeout";
-    readonly CRASHED: "crashed";
-    /** WU-1967: Spawn escalated to orchestrator (signal sent, prevents duplicates) */
-    readonly ESCALATED: "escalated";
-};
-/** Type for spawn status values */
-export type SpawnStatusValue = (typeof SpawnStatus)[keyof typeof SpawnStatus];
-/**
- * Array of valid spawn statuses
- */
-export declare const SPAWN_STATUSES: readonly ["pending", "completed", "timeout", "crashed", "escalated"];
-/**
- * Optional spawn intent source values.
- *
- * WU-1604: Explicit delegation intent should be distinguishable from legacy
- * spawn-style records when present.
- */
-export declare const SpawnIntent: {
-    readonly DELEGATION: "delegation";
-    readonly LEGACY_SPAWN: "legacy-spawn";
-};
-/** Type for spawn intent values */
-export type SpawnIntentValue = (typeof SpawnIntent)[keyof typeof SpawnIntent];
-/** Array of valid spawn intent values */
-export declare const SPAWN_INTENTS: readonly ["delegation", "legacy-spawn"];
-/**
- * Regex patterns for spawn validation
- */
-export declare const SPAWN_PATTERNS: {
-    /** Spawn ID format: spawn-{4 hex chars} */
-    SPAWN_ID: RegExp;
-    /** WU ID format: WU-{digits} */
-    WU_ID: RegExp;
-};
-/**
- * Spawn Event Schema
- *
- * Defines the structure for spawn registry events.
- * Uses append-only JSONL storage with event replay for state reconstruction.
- */
-export declare const SpawnEventSchema: z.ZodObject<{
-    id: z.ZodString;
-    parentWuId: z.ZodString;
-    targetWuId: z.ZodString;
-    lane: z.ZodString;
-    intent: z.ZodOptional<z.ZodEnum<{
-        delegation: "delegation";
-        "legacy-spawn": "legacy-spawn";
-    }>>;
-    spawnedAt: z.ZodString;
-    status: z.ZodEnum<{
-        completed: "completed";
-        timeout: "timeout";
-        pending: "pending";
-        crashed: "crashed";
-        escalated: "escalated";
-    }>;
-    completedAt: z.ZodNullable<z.ZodString>;
-    pickedUpAt: z.ZodOptional<z.ZodString>;
-    pickedUpBy: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/**
- * TypeScript type inferred from schema
- */
-export type SpawnEvent = z.infer<typeof SpawnEventSchema>;
-/**
- * Validates spawn event data against schema
- *
- * @param {unknown} data - Data to validate
- * @returns Validation result
- *
- * @example
- * const result = validateSpawnEvent(eventData);
- * if (!result.success) {
- *   result.error.issues.forEach(issue => {
- *     console.error(`${issue.path.join('.')}: ${issue.message}`);
- *   });
- * }
- */
-export declare function validateSpawnEvent(data: unknown): z.ZodSafeParseResult<{
-    id: string;
-    parentWuId: string;
-    targetWuId: string;
-    lane: string;
-    spawnedAt: string;
-    status: "completed" | "timeout" | "pending" | "crashed" | "escalated";
-    intent?: "delegation" | "legacy-spawn";
-    completedAt?: string;
-    pickedUpAt?: string;
-    pickedUpBy?: string;
-}>;
-/**
- * Generates a unique spawn ID from parent WU, target WU, and timestamp
- *
- * Format: spawn-XXXX (4 hex characters from SHA-256 hash)
- *
- * @param {string} parentWuId - Parent WU ID
- * @param {string} targetWuId - Target WU ID
- * @returns {string} Spawn ID in format spawn-XXXX
- *
- * @example
- * const id = generateSpawnId('WU-1000', 'WU-1001');
- * // Returns: 'spawn-a1b2'
- */
-export declare function generateSpawnId(parentWuId: string, targetWuId: string): string;
-//# sourceMappingURL=spawn-registry-schema.d.ts.map

package/dist/spawn-registry-schema.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"spawn-registry-schema.d.ts","sourceRoot":"","sources":["../src/spawn-registry-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;GAEG;AACH,eAAO,MAAM,WAAW;;;;;IAKtB,kFAAkF;;CAE1E,CAAC;AAEX,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE9E;;GAEG;AACH,eAAO,MAAM,cAAc,sEAAuE,CAAC;AAEnG;;;;;GAKG;AACH,eAAO,MAAM,WAAW;;;CAGd,CAAC;AAEX,mCAAmC;AACnC,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE9E,yCAAyC;AACzC,eAAO,MAAM,aAAa,yCAA0C,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,cAAc;IACzB,2CAA2C;;IAE3C,gCAAgC;;CAEjC,CAAC;AAeF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;iBAgC3B,CAAC;AAEH;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO;;;;;;;;;;;GAE/C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAU9E"}

package/dist/spawn-registry-schema.js

@@ -1,129 +0,0 @@
-/**
- * Spawn Registry Schema (WU-1944)
- *
- * Zod schemas for spawn event validation.
- * Defines schema for tracking sub-agent spawns by orchestrators.
- *
- * @see {@link packages/@lumenflow/cli/src/lib/__tests__/spawn-registry-store.test.ts} - Tests
- * @see {@link packages/@lumenflow/cli/src/lib/spawn-registry-store.ts} - Store implementation
- */
-import { z } from 'zod';
-import crypto from 'node:crypto';
-/**
- * Spawn status values
- */
-export const SpawnStatus = {
-    PENDING: 'pending',
-    COMPLETED: 'completed',
-    TIMEOUT: 'timeout',
-    CRASHED: 'crashed',
-    /** WU-1967: Spawn escalated to orchestrator (signal sent, prevents duplicates) */
-    ESCALATED: 'escalated',
-};
-/**
- * Array of valid spawn statuses
- */
-export const SPAWN_STATUSES = ['pending', 'completed', 'timeout', 'crashed', 'escalated'];
-/**
- * Optional spawn intent source values.
- *
- * WU-1604: Explicit delegation intent should be distinguishable from legacy
- * spawn-style records when present.
- */
-export const SpawnIntent = {
-    DELEGATION: 'delegation',
-    LEGACY_SPAWN: 'legacy-spawn',
-};
-/** Array of valid spawn intent values */
-export const SPAWN_INTENTS = ['delegation', 'legacy-spawn'];
-/**
- * Regex patterns for spawn validation
- */
-export const SPAWN_PATTERNS = {
-    /** Spawn ID format: spawn-{4 hex chars} */
-    SPAWN_ID: /^spawn-[0-9a-f]{4}$/,
-    /** WU ID format: WU-{digits} */
-    WU_ID: /^WU-\d+$/,
-};
-/**
- * Error messages for schema validation
- */
-const ERROR_MESSAGES = {
-    SPAWN_ID: 'Spawn ID must match pattern spawn-XXXX (e.g., spawn-a1b2)',
-    WU_ID: 'WU ID must match pattern WU-XXX (e.g., WU-1000)',
-    LANE_REQUIRED: 'Lane is required',
-    STATUS: `Status must be one of: ${SPAWN_STATUSES.join(', ')}`,
-    INTENT: `Intent must be one of: ${SPAWN_INTENTS.join(', ')}`,
-    TIMESTAMP_REQUIRED: 'Timestamp is required',
-    PICKUP_BY_REQUIRED: 'pickedUpBy must be a non-empty string when pickup is recorded',
-};
-/**
- * Spawn Event Schema
- *
- * Defines the structure for spawn registry events.
- * Uses append-only JSONL storage with event replay for state reconstruction.
- */
-export const SpawnEventSchema = z.object({
-    /** Unique spawn ID in format spawn-XXXX (4 hex chars from SHA hash) */
-    id: z.string().regex(SPAWN_PATTERNS.SPAWN_ID, { message: ERROR_MESSAGES.SPAWN_ID }),
-    /** Parent WU ID (the orchestrator that spawned this agent) */
-    parentWuId: z.string().regex(SPAWN_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
-    /** Target WU ID (the WU being executed by the spawned agent) */
-    targetWuId: z.string().regex(SPAWN_PATTERNS.WU_ID, { message: ERROR_MESSAGES.WU_ID }),
-    /** Lane for the spawned work */
-    lane: z.string().min(1, { message: ERROR_MESSAGES.LANE_REQUIRED }),
-    /** Optional intent source (delegation or legacy spawn path) */
-    intent: z.enum(SPAWN_INTENTS, { error: ERROR_MESSAGES.INTENT }).optional(),
-    /** ISO 8601 timestamp when spawn was recorded */
-    spawnedAt: z.string().datetime({ message: ERROR_MESSAGES.TIMESTAMP_REQUIRED }),
-    /** Current status of the spawned agent */
-    status: z.enum(SPAWN_STATUSES, {
-        error: ERROR_MESSAGES.STATUS,
-    }),
-    /** ISO 8601 timestamp when spawn completed (null if pending) */
-    completedAt: z.string().datetime().nullable(),
-    /** ISO 8601 timestamp when delegated work was picked up via wu:claim */
-    pickedUpAt: z.string().datetime().optional(),
-    /** Agent identity that picked up delegated work via wu:claim */
-    pickedUpBy: z.string().min(1, { message: ERROR_MESSAGES.PICKUP_BY_REQUIRED }).optional(),
-});
-/**
- * Validates spawn event data against schema
- *
- * @param {unknown} data - Data to validate
- * @returns Validation result
- *
- * @example
- * const result = validateSpawnEvent(eventData);
- * if (!result.success) {
- *   result.error.issues.forEach(issue => {
- *     console.error(`${issue.path.join('.')}: ${issue.message}`);
- *   });
- * }
- */
-export function validateSpawnEvent(data) {
-    return SpawnEventSchema.safeParse(data);
-}
-/**
- * Generates a unique spawn ID from parent WU, target WU, and timestamp
- *
- * Format: spawn-XXXX (4 hex characters from SHA-256 hash)
- *
- * @param {string} parentWuId - Parent WU ID
- * @param {string} targetWuId - Target WU ID
- * @returns {string} Spawn ID in format spawn-XXXX
- *
- * @example
- * const id = generateSpawnId('WU-1000', 'WU-1001');
- * // Returns: 'spawn-a1b2'
- */
-export function generateSpawnId(parentWuId, targetWuId) {
-    // Include timestamp and random bytes for uniqueness
-    const timestamp = Date.now().toString();
-    const randomBytes = crypto.randomBytes(4).toString('hex');
-    const input = `${parentWuId}:${targetWuId}:${timestamp}:${randomBytes}`;
-    const hash = crypto.createHash('sha256').update(input).digest('hex');
-    // Take first 4 hex chars
-    return `spawn-${hash.slice(0, 4)}`;
-}
-//# sourceMappingURL=spawn-registry-schema.js.map

package/dist/spawn-registry-schema.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"spawn-registry-schema.js","sourceRoot":"","sources":["../src/spawn-registry-schema.ts"],"names":[],"mappings":"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"}