openclaw-interchange

# @openclaw/interchange

The shared library that powers agent-to-agent communication via `.md` files.

## Usage

```javascript
import { writeMd, readMd, acquireLock } from '@openclaw/interchange';

// Write an interchange file atomically
await writeMd('ops/status.md', { skill: 'crm', status: 'healthy' }, '## Status\nAll systems go.');

// Read it back
const { meta, content } = readMd('ops/status.md');
```

## Key Features
- Atomic writes (tmp + fsync + rename)
- Deterministic serialization (sorted keys, stable YAML)
- Advisory file locking with stale lock detection
- YAML frontmatter parsing
- Schema validation
- Circuit breaker pattern
- Generation tracking + content hashing

# @openclaw/interchange

[![Tests](https://img.shields.io/badge/tests-32%20passing-brightgreen)]() [![Node](https://img.shields.io/badge/node-%3E%3D18-blue)]() [![License: MIT](https://img.shields.io/badge/license-MIT-yellow)]()

> The shared .md interchange library that every OpenClaw skill builds on.

Interchange provides atomic file I/O, deterministic serialization, YAML frontmatter parsing, advisory locking, and schema validation for `.md` interchange files. It's the foundation layer — ensuring that every skill speaks the same language and every write is crash-safe.

## Features

- **Atomic writes** — tmp + fsync + rename protocol prevents partial writes
- **Deterministic serialization** — same input always produces byte-identical output
- **YAML frontmatter** — read/write structured metadata in `.md` files
- **Advisory locking** — prevent concurrent writes from multiple agents
- **Schema validation** — validate frontmatter and interchange layers
- **Content hashing & generations** — track changes with generation IDs and content hashes
- **Staleness detection** — check if interchange files need regeneration
- **DB-to-interchange reconciliation** — sync database state to `.md` files
- **Circuit breaker** — resilient I/O with automatic failure detection
- **Helpers** — slugify, table formatting, currency formatting, relative time

## Quick Start

```bash
cd skills/interchange
npm install
```

```js
import { readMd, writeMd, acquireLock, releaseLock, validateFrontmatter } from '@openclaw/interchange';

// Read a .md interchange file
const doc = readMd('path/to/file.md');
console.log(doc.frontmatter, doc.body);

// Atomic write with frontmatter
writeMd('path/to/output.md', {
  frontmatter: { type: 'report', generated: new Date().toISOString() },
  body: '## Summary\nAll systems operational.'
});

// Advisory locking
const lock = acquireLock('path/to/file.md');
try {
  // ... safe writes ...
} finally {
  releaseLock(lock);
}
```

## API Reference

| Export | Descrip...