@@ -41,7 +41,7 @@ of this boundary. It records the pinned source commit and installed engine versi
 | Ordered document text | Supported through a strict type-6 dictionary bridge plus the pinned fork | Import stores normalized document rows; export creates a temporary UTF-8 SAV source and has IBM I/O copy the records into SAV or ZSAV without invalidating ZSAV dictionary offsets. |
 | Print and write formats independently | Supported as raw IBM I/O tuples | The adapter stores both tuples separately and writes them without collapsing either value. |
 | Variable sets | Supported through raw IBM I/O | The adapter stores source sets in the extension catalog and writes them through the raw dictionary setter. Invalid target definitions fail before data are written. |
-| Legacy compatible variable names | Fail-closed on export | A compatible name that differs from the long source name is retained in the catalog, but cannot be set through the public writer. Export requires `compatible-variable-name-not-exportable`. |
+| Legacy compatible variable names | Supported through the strict dictionary bridge | The adapter stores the short-name mapping and rewrites both the fixed variable record and long-name extension before export. |
 | Source encoding | UTF-8 fidelity only | UTF-8 is supported. A legacy code page is retained in metadata, but export requires `source-encoding-not-preserved` because the writer has no legacy-code-page preservation contract. |
 | Custom attributes with one value | Supported | File and variable scalar attributes round trip through the normalized attribute catalog. |
 | Custom-attribute value arrays | Supported through raw IBM I/O | The adapter represents an array as IBM SPSS `Name[1]`, `Name[2]`, … members and reconstructs the ordered array in the normalized catalog. |
 
@@ -38,7 +38,7 @@ def capability_matrix() -> Mapping[str, Any]:
             "multiple_response_sets": "supported",
             "variable_alignment": "supported",
             "variable_sets": "supported",
-            "compatible_variable_names": "fail-closed-on-export",
+            "compatible_variable_names": "supported",
             "custom_attributes": {
                 "scalar_values": "supported",
                 "ordered_value_arrays": "supported",
 
@@ -1,4 +1,4 @@
-"""Small, fail-closed helpers for the SPSS type-6 document record.
+"""Small, fail-closed helpers for selected raw SPSS dictionary records.
 
 This is not a second SAV engine: pyspssio still owns values and the normal
 dictionary. IBM I/O exposes copying document records but not their text.
@@ -51,14 +51,155 @@ def write_document_lines(path: str | Path, lines: Iterable[str], *, encoding: st
     if len(documents) > 1:
         raise RawDictionaryError("SAV dictionary contains more than one document record.")
     replacement = _document_record(lines, encoding=encoding, byte_order=byte_order)
+    terminator = next(record for record in records if record.record_type == 999)
     if documents:
         current = documents[0]
-        target.write_bytes(data[: current.start] + replacement + data[current.end :])
+        updated = data[: current.start] + replacement + data[current.end :]
+    else:
+        extension = next((record for record in records if record.record_type == 7), None)
+        insertion = extension.start if extension else terminator.start
+        updated = data[:insertion] + replacement + data[insertion:]
+    target.write_bytes(_shift_zsav_offsets(
+        updated,
+        original_data_start=terminator.end,
+        delta=len(updated) - len(data),
+        byte_order=byte_order,
+    ))
+
+
+def write_compatible_names(
+    path: str | Path, names: dict[str, str], *, encoding: str,
+) -> None:
+    """Set exact legacy short names without changing long source variable names.
+
+    IBM I/O has no compatible-name setter.  The standard long-name extension
+    and the fixed 8-byte variable records contain the complete mapping, so this
+    narrowly rewrites only those two dictionary locations.  Every requested
+    source name must have a long-name record; otherwise the operation fails
+    instead of silently deriving another name.
+    """
+    if not names:
         return
-    extension = next((record for record in records if record.record_type == 7), None)
+    target = Path(path)
+    data = target.read_bytes()
+    byte_order, records = _records(data)
     terminator = next(record for record in records if record.record_type == 999)
-    insertion = extension.start if extension else terminator.start
-    target.write_bytes(data[:insertion] + replacement + data[insertion:])
+    long_names = next(
+        (
+            record for record in records
+            if record.record_type == 7 and _int(data, record.start + 4, byte_order) == 13
+        ),
+        None,
+    )
+    if long_names is None:
+        raise RawDictionaryError("SAV dictionary has no long-variable-name record.")
+    payload_start = long_names.start + 16
+    payload = data[payload_start : long_names.end]
+    pairs = _long_name_pairs(payload, encoding)
+    replacements: dict[str, str] = {}
+    updated_pairs: list[tuple[str, str]] = []
+    unresolved = set(names)
+    for short_name, long_name in pairs:
+        replacement = names.get(long_name)
+        if replacement is None:
+            updated_pairs.append((short_name, long_name))
+            continue
+        replacements[short_name] = _validated_compatible_name(replacement)
+        updated_pairs.append((replacements[short_name], long_name))
+        unresolved.remove(long_name)
+    if unresolved:
+        missing = ", ".join(sorted(unresolved))
+        raise RawDictionaryError(
+            "Compatible-name update requires a long-name record for: " + missing
+        )
+
+    mutable = bytearray(data)
+    for record in records:
+        if record.record_type != 2:
+            continue
+        short_name = bytes(mutable[record.start + 24 : record.start + 32]).decode(encoding).rstrip(" ")
+        replacement = replacements.get(short_name)
+        if replacement is not None:
+            mutable[record.start + 24 : record.start + 32] = replacement.encode("ascii").ljust(8, b" ")
+
+    new_payload = b"	".join(
+        short_name.encode("ascii") + b"=" + long_name.encode(encoding)
+        for short_name, long_name in updated_pairs
+    )
+    header = bytearray(mutable[long_names.start : long_names.start + 16])
+    header[12:16] = _pack(len(new_payload), byte_order)
+    updated = (
+        bytes(mutable[: long_names.start]) + bytes(header) + new_payload
+        + bytes(mutable[long_names.end :])
+    )
+    target.write_bytes(_shift_zsav_offsets(
+        updated,
+        original_data_start=terminator.end,
+        delta=len(updated) - len(data),
+        byte_order=byte_order,
+    ))
+
+
+def _long_name_pairs(payload: bytes, encoding: str) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    for raw_pair in payload.split(b"	"):
+        try:
+            raw_short, raw_long = raw_pair.split(b"=", maxsplit=1)
+            short_name = raw_short.decode("ascii")
+            long_name = raw_long.decode(encoding)
+        except (UnicodeDecodeError, ValueError) as error:
+            raise RawDictionaryError("Invalid SAV long-variable-name record.") from error
+        pairs.append((short_name, long_name))
+    return pairs
+
+
+def _validated_compatible_name(value: str) -> str:
+    encoded = str(value).encode("ascii")
+    if not 1 <= len(encoded) <= 8:
+        raise RawDictionaryError("SPSS compatible variable names must contain one to eight ASCII bytes.")
+    first = encoded[:1]
+    rest = encoded[1:]
+    if not (first.isalpha() or first == b"@"):
+        raise RawDictionaryError("SPSS compatible variable names must start with an ASCII letter or @.")
+    if any(character not in b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.$#"
+           for character in rest):
+        raise RawDictionaryError("SPSS compatible variable name contains an unsupported character.")
+    return encoded.decode("ascii")
+
+
+def _shift_zsav_offsets(
+    data: bytes, *, original_data_start: int, delta: int, byte_order: str,
+) -> bytes:
+    """Shift all absolute ZSAV data offsets after a dictionary-size rewrite."""
+    if not delta or data[:4] != b"$FL3":
+        return data
+    adjusted = bytearray(data)
+    data_start = original_data_start + delta
+    _need(adjusted, data_start, 24)
+    original_zheader = _int64(adjusted, data_start, byte_order)
+    original_ztrailer = _int64(adjusted, data_start + 8, byte_order)
+    trailer_length = _int64(adjusted, data_start + 16, byte_order)
+    if original_zheader != original_data_start:
+        raise RawDictionaryError("Unexpected ZSAV data-header offset.")
+    _set_int64(adjusted, data_start, original_zheader + delta, byte_order)
+    _set_int64(adjusted, data_start + 8, original_ztrailer + delta, byte_order)
+    trailer_start = original_ztrailer + delta
+    if trailer_length < 24:
+        raise RawDictionaryError("Invalid ZSAV data-trailer length.")
+    _need(adjusted, trailer_start, 24)
+    block_count = _int(adjusted, trailer_start + 20, byte_order)
+    if block_count < 0 or trailer_length != 24 + (block_count * 24):
+        raise RawDictionaryError("Invalid ZSAV data-trailer block metadata.")
+    _need(adjusted, trailer_start + 24, block_count * 24)
+    for index in range(block_count):
+        descriptor = trailer_start + 24 + (index * 24)
+        _set_int64(adjusted, descriptor, _int64(adjusted, descriptor, byte_order) + delta, byte_order)
+        _set_int64(
+            adjusted, descriptor + 8,
+            _int64(adjusted, descriptor + 8, byte_order) + delta,
+            byte_order,
+        )
+    return bytes(adjusted)
 
 
 def _document_record(lines: Iterable[str], *, encoding: str, byte_order: str) -> bytes:
@@ -160,6 +301,14 @@ def _int(data: bytes, offset: int, byte_order: str) -> int:
     return int.from_bytes(data[offset : offset + 4], byte_order, signed=True)
 
 
+def _int64(data: bytes, offset: int, byte_order: str) -> int:
+    return int.from_bytes(data[offset : offset + 8], byte_order, signed=True)
+
+
+def _set_int64(data: bytearray, offset: int, value: int, byte_order: str) -> None:
+    data[offset : offset + 8] = int(value).to_bytes(8, byte_order, signed=True)
+
+
 def _round4(value: int) -> int:
     return (value + 3) & ~3
 
 
@@ -18,7 +18,12 @@
 import pandas as pd
 import pyspssio
 
-from .raw_dictionary import RawDictionaryError, read_document_lines, write_document_lines
+from .raw_dictionary import (
+    RawDictionaryError,
+    read_document_lines,
+    write_compatible_names,
+    write_document_lines,
+)
 from .dictionary import (
     attribute_pairs,
     attribute_values,
@@ -190,7 +195,7 @@ def inspect_sav(source: str | Path) -> dict[str, Any]:
     metadata, loss_report = _dictionary(source_path)
     names = list(metadata.get("var_names") or [])
     variables = _variables(metadata, names)
-    loss_report = _merge_loss_reports(tuple(loss_report.values()), _compat_name_loss_report(variables))
+    loss_report = _merge_loss_reports(tuple(loss_report.values()))
     return {
         "source_format": source_path.suffix[1:].upper(),
         "engine": engine_identity(),
@@ -220,7 +225,7 @@ def import_sav_dataset(*, source: str | Path, database_url: str, dataset_id: str
     # frame read's values where a future pyspssio version exposes more there.
     metadata = {**dictionary, **metadata}
     variables = _variables(metadata, list(frame.columns))
-    loss_report = _merge_loss_reports(tuple(loss_report.values()), _compat_name_loss_report(variables))
+    loss_report = _merge_loss_reports(tuple(loss_report.values()))
     result = create_wide_dataset(
         database_url=database_url,
         dataset_id=dataset_id,
@@ -364,6 +369,16 @@ def _write_with_dictionary_bridge(
             writer.copy_documents_from(document_source)
         writer.commit_header()
         writer.write_data(frame)
+    write_compatible_names(
+        destination,
+        {
+            str(variable["source_name"]): str(variable["compat_name"])
+            for variable in variables
+            if variable.get("compat_name")
+            and str(variable["compat_name"]).casefold() != str(variable["source_name"]).casefold()
+        },
+        encoding="UTF-8",
+    )
 
 def _catalog_format(variable: dict[str, Any], key: str) -> tuple[int, int, int]:
     encoded = variable.get(key)
@@ -445,37 +460,6 @@ def _engine_loss_report(metadata: dict[str, Any]) -> dict[str, dict[str, Any]]:
     return events
 
 
-def _compat_name_loss_report(variables: list[dict[str, Any]]) -> tuple[dict[str, Any], ...]:
-    """Report legacy SPSS compatible names the writer cannot set explicitly.
-
-    A compatible name is meaningful only when it differs from the long source
-    variable name. ``pyspssio`` exposes these names while reading, but its
-    public writer metadata has no ``var_compat_names`` input. It may derive a
-    name today, but that is not a preservation contract: export must therefore
-    require an explicit, auditable acceptance rather than silently rederive or
-    rename the value.
-    """
-    events: list[dict[str, Any]] = []
-    for variable in variables:
-        source_name = str(variable["source_name"])
-        compat_name = variable.get("compat_name")
-        if compat_name is None or str(compat_name).casefold() == source_name.casefold():
-            continue
-        events.append({
-            "code": "compatible-variable-name-not-exportable",
-            "detail": (
-                "pyspssio exposes the source compatible variable name but its public "
-                "writer API cannot set or guarantee preservation of that name."
-            ),
-            "details": {
-                "source_name": source_name,
-                "compatible_name": str(compat_name),
-                "physical_name": str(variable["physical_name"]),
-            },
-        })
-    return tuple(events)
-
-
 def _export_loss_report(
     dataset: dict[str, Any], variables: list[dict[str, Any]],
 ) -> tuple[dict[str, Any], ...]:
@@ -486,10 +470,8 @@ def _export_loss_report(
             "detail": "The pyspssio writer has no source-encoding preservation contract for this legacy code page.",
             "details": {"source_encoding": dataset.get("source_encoding")},
         })
-    events.extend(_compat_name_loss_report(variables))
     return tuple(events)
 
-
 def _merge_loss_reports(*reports: tuple[dict[str, Any], ...]) -> tuple[dict[str, Any], ...]:
     events: dict[str, dict[str, Any]] = {}
     for report in reports:
 
@@ -56,7 +56,7 @@ def test_capability_matrix_is_public_and_cli_matches_engine_boundary(capsys) ->
         "multiple_response_sets": "supported",
         "variable_alignment": "supported",
         "variable_sets": "supported",
-        "compatible_variable_names": "fail-closed-on-export",
+        "compatible_variable_names": "supported",
         "custom_attributes": {
             "scalar_values": "supported",
             "ordered_value_arrays": "supported",
 
@@ -6,7 +6,11 @@
 import pytest
 
 import openstatspec
-from openstatspec.spss.raw_dictionary import read_document_lines, write_document_lines
+from openstatspec.spss.raw_dictionary import (
+    read_document_lines,
+    write_compatible_names,
+    write_document_lines,
+)
 
 
 def _source_with_documents(path: Path, lines: list[str]) -> None:
@@ -65,3 +69,20 @@ def test_document_lines_import_from_zsav_and_export_to_sav(tmp_path: Path) -> No
     )
     assert read_document_lines(destination, encoding="UTF-8") == expected
     assert pyspssio.read_sav(str(destination))[0]["answer"].tolist() == [1.0, 2.0]
+
+
+def test_document_and_compatible_name_round_trip_to_zsav(tmp_path: Path) -> None:
+    source = tmp_path / "source.sav"
+    destination = tmp_path / "destination.zsav"
+    database = f"sqlite:///{tmp_path / 'combined.sqlite'}"
+    source_name = "long_variable_name"
+    pyspssio.write_sav(str(source), pd.DataFrame({source_name: [7.0]}))
+    write_document_lines(source, ["Combined dictionary fixture."], encoding="UTF-8")
+    write_compatible_names(source, {source_name: "ANSWER"}, encoding="UTF-8")
+
+    openstatspec.import_sav(source, database_url=database, dataset_id="combined")
+    openstatspec.export_sav(database_url=database, dataset_id="combined", destination=destination)
+
+    assert read_document_lines(destination, encoding="UTF-8") == ["Combined dictionary fixture."]
+    assert pyspssio.read_metadata(str(destination))["var_compat_names"][source_name] == "ANSWER"
+    assert pyspssio.read_sav(str(destination))[0][source_name].tolist() == [7.0]