Capability Registry and Workbook Compatibility Passport

WolfXL exposes a local, non-mutating compatibility decision before a workbook is entrusted to an operation. Both documents are deterministic JSON and bind their claims to the installed WolfXL engine version.

The capability registry is generated from Migration Doctor's packaged projection of docs/migration/_compat_spec.py. It is not a second support matrix. Registry construction fails when a canonical WOM v3 operation is missing, duplicated, invalid, or assessed without checked-in evidence.

Capability registry

wolfxl-doctor registry > wolfxl-capabilities.json

The document includes:

• the installed engine version and native build identity;
• the compatibility-spec SHA-256 and registry SHA-256;
• the closed capability-status and preservation-disposition vocabularies;
• evidence, required verification, and remediation for each capability;
• the local host contract, admitted source formats, and its evidence.

The registry has no timestamp, so the same engine and canonical catalog produce byte-identical canonical JSON.

The admitted source-format list is projected from the runtime's WOM admission declaration. Registry generation fails closed if that runtime-owned declaration is missing, malformed, or drifts from the packaged projection.

Workbook Compatibility Passport

wolfxl-doctor passport model.xlsx \
  --operation set_cells \
  --operation set_formulas > model.passport.json

The passport binds the read-only inspection to the workbook byte SHA-256, artifact size, installed engine version/build identity, and exact registry SHA-256. It does not serialize the workbook path or cell values. Paths are inspected through a temporary byte-for-byte snapshot, preventing the report from describing a different file if the source changes concurrently.

A compatible decision also requires the exact native WOM runtime package admission to succeed under its strict limits, required-part checks, relationship validation, and sheet resolution. ZIP readability alone is not sufficient.

For packages admitted by that runtime, inspection.source_format and the passport artifact's source_format both use the runtime's exact xlsx or xlsm classification. This intentionally refines the loader's generic OOXML classification for macro-enabled content so one admitted source never reports conflicting formats.

Decisions are conservative:

Decision	Exit	Meaning
compatible	0	Every requested operation is supported and inspection found no review boundary.
review_required	3	Operations are supported, but concrete workbook risks or incomplete coverage require verification.
unsupported	2	At least one operation, source format, terminal inspection capability, or concrete diagnostic is unsupported.
unassessed	3	No operation was requested, or no canonical evidence mapping exists.

An inspection preservation record only describes the non-mutating inspection. It is not a promise that a later save will preserve the feature. Use the passport's requested-operation dispositions and required verification before execution.

Python API

from wolfxl.doctor import create_workbook_passport

passport = create_workbook_passport(
    "model.xlsx",
    requested_operations=("set_cells", "set_formulas"),
)
document = passport.to_dict()

The API also accepts bytes and binary streams. Seekable streams are restored to their initial position; non-seekable streams are consumed once.

This first slice covers JSON and canonical WOM v3 operation evidence. HTML and SARIF are intentionally separate renderers for a later change so the registry and decision contract remain small and reviewable.