V4A Diff

Context-anchored diff engine for LLM-powered file editing

What is V4A?

V4A is a context-anchored diff format designed for LLM tool calling. Instead of line numbers, hunks use @@ text anchors to locate edits - making diffs resilient to file changes between turns. This package parses V4A diffs, applies them to source text, and returns both the patched result and structured diff metadata with line numbers.

Features

• CRUD modes - Update, create, delete, and move files in a single API.
• Token efficient - Returns only changed lines, not the entire file.
• Instant rollback - Original source included in result, no manual tracking.
• Structured diff - Line-by-line add/delete/equal metadata with line numbers.
• Character-level diff - Optional intra-line segments via grapheme-aware refine.
• Smart matching - Fuzzy context resolution with whitespace and Unicode tolerance.

Installation

Deno (JSR):

deno add jsr:@neabyte/v4a-diff

npm:

npm install @neabyte/v4a-diff

CDN (jsDelivr/esm.sh):

<script type="module">
  import V4A from 'https://cdn.jsdelivr.net/npm/@neabyte/v4a-diff/dist/index.mjs'
</script>

Or via esm.sh:

<script type="module">
  import V4A from 'https://esm.sh/@neabyte/v4a-diff'
</script>

Usage

[!WARNING] This is a pure text-to-text API with no filesystem I/O, designed to run in any environment including browsers, CLI, and terminal applications. Filesystem operations such as reading, writing, and deleting files are left to the consumer.

import V4A from '@neabyte/v4a-diff'

// Update an existing file
const result = V4A.apply(
  'function add(a, b) {\n  return a - b\n}',
  '@@\n function add(a, b) {\n-  return a - b\n+  return a + b\n }'
)

console.log(result.source)
// function add(a, b) {
//   return a - b
// }

console.log(result.text)
// function add(a, b) {
//   return a + b
// }

console.log(result.diff)
// [
//   { type: 'equal',  value: 'function add(a, b) {', oldLine: 1, newLine: 1 },
//   { type: 'delete', value: '  return a - b',       oldLine: 2, newLine: null },
//   { type: 'add',    value: '  return a + b',       oldLine: null, newLine: 2 },
//   { type: 'equal',  value: '}',                    oldLine: 3, newLine: 3 }
// ]

With *** Begin Patch envelope

const result = V4A.apply(
  'const x = 1',
  '*** Begin Patch\n*** Update File: /src/config.ts\n@@\n-const x = 1\n+const x = 2\n*** End Patch'
)
// result.text === 'const x = 2'

Create a new file

const result = V4A.apply(
  '',
  '+export const PORT = 8080\n+export const HOST = "localhost"',
  'create'
)
// result.text === 'export const PORT = 8080\nexport const HOST = "localhost"'

Delete a file

[!NOTE] Source is needed to produce the structured diff output.

const result = V4A.apply('const x = 1\nconst y = 2', '*** Delete File: /src/config.ts', 'delete')
// result.text === ''
// result.source === 'const x = 1\nconst y = 2'

Move a file (apply diff at new path)

[!NOTE] Source is needed to produce the structured diff output.

// Move with edits
const result = V4A.apply(
  'const x = 1',
  '*** Move to: /src/new-path.ts\n@@\n-const x = 1\n+const x = 2',
  'move'
)
// result.text === 'const x = 2'

// Move without edits (pure rename)
const renamed = V4A.apply('const x = 1\nconst y = 2', '*** Move to: /src/new-path.ts', 'move')
// renamed.text === 'const x = 1\nconst y = 2'
// renamed.diff lines are all { type: 'equal' }

Multi-hunk edits

const result = V4A.apply(
  'function add(a, b) {\n  return a - b\n}\nfunction sub(a, b) {\n  return a + b\n}',
  '@@ function add(\n function add(a, b) {\n-  return a - b\n+  return a + b\n }\n@@ function sub(\n function sub(a, b) {\n-  return a + b\n+  return a - b\n }'
)

Character-level diff

const result = V4A.apply('const x = 1', '@@\n-const x = 1\n+const x = 2')
const refined = V4A.refine(result.diff)
// refined[1].segments
// [
//   { type: 'equal', value: 'const x = ' },
//   { type: 'add',   value: '2' }
// ]

API

V4A.apply(sourceText, diffText, mode?)

| Parameter | Type | Description | | ------------ | --------------- | --------------------------------------------------------- | | sourceText | string | Original file content | | diffText | string | V4A format diff string | | mode | ApplyDiffMode | 'update' (default), 'create', 'delete', or 'move' |

Returns: ApplyDiffResult

type ApplyDiffResult = {
  text: string // Patched output text
  diff: DiffLine[] // Structured line-by-line diff
  source: string // Original source text for rollback
}

type DiffLine = {
  type: 'add' | 'delete' | 'equal'
  value: string // Line content
  oldLine: number | null // Source line number (null for adds)
  newLine: number | null // Result line number (null for deletes)
  segments?: CharSegment[] // Intra-line segments (only after refine)
}

type CharSegment = {
  type: 'add' | 'delete' | 'equal'
  value: string // Segment content
}

V4A.refine(diff)

Adds character-level (intra-line) detail on top of a line diff. It pairs adjacent delete and add lines, runs a grapheme-level diff via Intl.Segmenter, and attaches a segments array to each changed line. Other lines pass through untouched. The core apply() output stays the single source of truth - value for the whole line, segments for the char-by-char view.

| Parameter | Type | Description | | --------- | ------------ | ----------------------------- | | diff | DiffLine[] | Line diff from apply().diff |

Returns: DiffLine[] with segments on changed lines.

const result = V4A.apply('return a - b', '@@\n-return a - b\n+return a + b')
const refined = V4A.refine(result.diff)

console.log(refined[1].segments)
// [
//   { type: 'equal', value: 'return a ' },
//   { type: 'add',   value: '+' },
//   { type: 'equal', value: ' b' }
// ]

[!NOTE] refine is safe by default - non-array input returns [], non-string values pass unrefined, and shared prefixes/suffixes are trimmed before diffing.

V4A Diff Format

*** Begin Patch
*** Update File: {path}
@@ {anchor_text}
 context line (space prefix, exact copy from file)
-removed line (must match file exactly)
+added line
*** End Patch

Other file operation headers:

*** Add File: {path}
*** Delete File: {path}
*** Move to: {new_path}

• @@ followed by text anchors to a matching line in the source file.
• A bare @@ alone means "start of file."
• Every line in a hunk must start with ``(space),-, or +.
• *** Add File: with + prefixed lines creates new files.
• *** Delete File: marks a file for deletion.
• *** Move to: renames/moves a file while applying edits.

LLM Tool Schemas

Pre-built schemas for tool calling live in schema/:

• schema/openai.json - OpenAI function calling format
• schema/anthropic.json - Anthropic tool use format

Build

npm run build

Testing

deno task check

deno task test

Acknowledgements

This is a clean-room TypeScript reimplementation of the V4A context-anchored diff format, with additional features including fuzz matching, envelope stripping, and structured diff output.

Based on the V4A format specification and reference implementations by OpenAI:

• Apply Patch Tool Documentation
• Rust Reference (codex apply-patch)
• TypeScript Reference (openai-agents-js)

License

This project is licensed under the MIT license. See the LICENSE file for details.