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

• 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.
• 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

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"'

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 }'
)

API

V4A.apply(sourceText, diffText, mode?)

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)
}

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

• @@ 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.

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.