Node.js Temporal Stability

Provide temporal stability to Node.js applications by automatically fixing files with inconsistent timestamps that can break change detection, file watchers, and other time-sensitive operations.

Problem

External tools and processes sometimes create files with problematic timestamps that break Node.js applications:

• Future timestamps - Files with modification/access times in the future
• Inconsistent ordering - Files where mtime is significantly newer than atime
• Temporal anomalies - Files that violate expected timestamp relationships

These issues commonly affect:

• Claude Code - Change detection fails with future timestamps
• File watchers - May not trigger correctly with inconsistent times
• Build tools - Can make incorrect incremental build decisions
• Development servers - Hot reload systems may malfunction

How It Works

This package provides temporal stability by monkey-patching Node.js's fs module to:

1. Detect files with problematic timestamps during stat operations
2. Fix the file by touching it to set consistent current timestamps
3. Return corrected stats transparently to your application

The fix operates at the JavaScript level, intercepting filesystem calls before they reach your application logic.

Usage

Method 1: Environment Variable (Universal)

NODE_OPTIONS="--require node-stability" your-node-app
NODE_OPTIONS="--require node-stability" npm start
NODE_OPTIONS="--require node-stability" yarn dev

Method 2: Direct Require (In Code)

// Add this at the top of your main application file
require('node-stability');

Method 3: Command Line Flag

node -r node-stability your-script.js

Application-Specific Wrappers

Claude Code

./claude-stability -p --allowedTools="Edit Read" "append something to file.txt"

The claude-stability wrapper automatically provides temporal stability to Claude Code sessions.

Generic Node.js Applications

./node-stability your-node-app
./node-stability npm start
./node-stability yarn dev

The node-stability wrapper works with any Node.js application.

Testing

Run the basic test to verify temporal stability:

npm test

Or run individual tests:

node test.js                    # Basic functionality test
node comprehensive-test.js      # All timestamp scenarios

Debug Mode

Enable detailed logging to see what timestamps are being fixed:

NODE_TIMESTAMP_DEBUG=1 node your-app.js

Advantages

• ✅ No system privileges - Works entirely in user space
• ✅ Universal compatibility - Works with any Node.js application
• ✅ Transparent operation - Applications see corrected timestamps seamlessly
• ✅ No kernel patches - Pure JavaScript solution
• ✅ Easy integration - Single require statement
• ✅ Portable - Works across different operating systems

When You Need This

Use this package when you encounter:

• Change detection systems failing with "file modified in future" errors
• File watchers not triggering on legitimately changed files
• Build tools making incorrect incremental decisions
• Development servers failing to hot-reload
• Applications that rely on consistent filesystem timestamp ordering

Technical Details

Temporal Stability is achieved by:

1. Intercepting Node.js fs.stat* operations via monkey patching
2. Analyzing timestamps for temporal inconsistencies
3. Automatically fixing problematic files using fs.utimes
4. Providing corrected metadata transparently to applications

The package patches all stat variants: statSync, lstatSync, stat, lstat, and their promises equivalents.

License

LGPL-3.0+