V1 Compatibility

MarkBack V2 is fully backward-compatible with V1 files. V1 files parse transparently -- the parser maps old headers to their V2 equivalents and emits W010 warnings so you know what to update.

Header Mapping

V1 Header	V2 Header	Notes
@uri	@id	Value preserved as-is; no URI validation in V2
@source	@file	Path and line ranges preserved
@prior	@input	Path and line ranges preserved

V1 compact records (@source ... <<<) are also recognized.

What Changed

V1 Behavior	V2 Behavior
@uri requires RFC 3986 (E003 on failure)	@id is a plain string, no validation
@source + inline content is an error (E005)	@file + inline content is valid (@file is provenance, content is snapshot)
Sidecars: name.label.txt, name.feedback.txt	Sidecars: name.ext.mb (V1 patterns still discovered)
No version declaration	%markback 2 (optional but recommended)
No tags	@tag header for categorization
No sweep pattern	%scope + %covers for meaningful absence

Upgrading

The simplest path is the CLI:

# Upgrade in place
mb --upgrade *.mb

# Preview without writing
mb --upgrade *.mb --dry-run

This replaces V1 headers in place and adds %markback 2. Use --dry-run to see which files would change without writing.

To upgrade manually:

1. Replace @uri with @id
2. Replace @source with @file
3. Replace @prior with @input
4. Rename sidecars from name.label.txt to name.ext.mb
5. Optionally add %markback 2 at the top
6. Optionally add @tag headers

Staying on V1

If you can't upgrade yet, V1 files will continue to work. The parser handles them transparently and all tooling (lint, list, stats, normalize) works with V1 input. The only difference is W010 warnings indicating that V1 headers were detected.

To suppress these warnings in your workflow, you can filter them out:

mb --lint data.mb 2>&1 | grep -v W010

Retired Lint Codes

These error codes are no longer emitted when parsing V2 files:

Code	V1 Description	V2 Status
E003	Malformed URI in @uri	Retired: @id has no format validation
E005	Content present when @source specified	Retired: @file + inline content is valid

V1 API Compatibility (Python)

The Python package provides V1 compatibility aliases:

# These V1 names still work but map to V2 equivalents
from markback.types import SourceRef      # alias for FileRef
record.uri       # property alias for record.id
record.source    # property alias for record.file
record.prior     # property alias for record.input

V1 writer functions are also aliased:

from markback import write_file              # alias for write
from markback import write_record_canonical  # alias for write_string (single record)
from markback import normalize_file          # alias for normalize