# LAVS-001 Conformance Test Suite

| | |
|---|---|
| **Status** | Adopted reference |
| **Suite version** | 1.0 |
| **Targets** | LAVS-001.0, LAVS-001.1, LAVS-001.2 |
| **Suite source** | `https://github.com/guitargnarr/lavs-format/blob/main/scripts/conformance.ts` |
| **License** | The suite source is proprietary (Project Lavos LLC); this documentation is CC BY 4.0 |

This document specifies the reference conformance test suite for the [LAVS-001](https://github.com/guitargnarr/lavs-format/blob/main/spec/LAVS-001.md) sealed-container format. Independent implementations of LAVS-001 decoders, viewers, marketplace tools, and gallery operators **SHOULD** run their output and inputs through this suite to verify spec conformance.

The suite is a self-contained TypeScript program. The semantic checks it performs are listed below in detail; any implementer building against LAVS-001 in another language may reproduce these checks from this document alone — the suite source itself is not required.

## What the suite checks

For each `.lavs` file passed as input, the suite runs the following checks. Some are required for conformance; others are warnings (forward-compatibility surface) that do not fail unless the suite is run in `--strict` mode.

### Structural (required)

1. **Magic header.** The first four bytes are `0x4C 0x41 0x56 0x53` (`LAVS`). Per LAVS-001 §3.1.
2. **Decoder runs without error.** The reference decoder parses the file from byte 0 to the CRC32 footer. Per LAVS-001 §3–§8.
3. **Spec major.** `specMajor == 1`. v1.0/v1.1/v1.2 readers MUST refuse `specMajor > 1`. Per LAVS-001 §11.2.
4. **CRC32 valid.** The CRC32 footer matches the CRC32 of the edition block bytes, using the standard polynomial `0xEDB88320`, init `0xFFFFFFFF`, final XOR `0xFFFFFFFF`. Per LAVS-001 §8.3.
5. **Fast-path consistency.** The fast-path edition reader (§10.6) returns the same title, author, edition number, and CRC validity as the full decode.
6. **Profile first.** The first scene object is a Profile (type 1). Per LAVS-001 §7 Type 1.
7. **Artboard second.** Exactly one Artboard (type 2), positioned immediately after the Profile. Per LAVS-001 §7 Type 2.
8. **Mesh references resolve.** Every Mesh object's `bufferRef` and `materialRef` point to declared Buffer and Material objects in document order. Per LAVS-001 §6.3 and §7 Type 5.
9. **PalettePin validity.** Every PalettePin's `paletteName` is either a canonical palette identifier (`amber`, `teal`, `violet`, `rose`, `bone`, `sky`, `orange`) or a 7-character custom hex (`#RRGGBB`). Per LAVS-001 §7 Type 17.

### Edition (required)

10. **Required Edition fields.** Edition has `title` (700), `author` (701), `editionNumber` (702), `editionTotal` (703), `year` (704), and `license` (705). Per LAVS-001 §8.1.
11. **License non-empty.** `edition.license` is a non-empty string.
12. **Edition number in range.** `editionNumber > 0`, and either `editionTotal == 0` (open edition) or `editionNumber <= editionTotal`.
13. **Signature blob.** If `signatureAlgorithm` is declared, a signature blob (LEB128 length + bytes) is present in the edition block. Per LAVS-001 §8.2.

### LAVS-001.2 Environment (required when applicable)

14. **At most one Environment.** A scene contains zero or one Environment objects (type 19). Per LAVS-001 §6.5.
15. **Environment feature declared.** If an Environment is present, `Profile.features` includes the `environment` flag. Per LAVS-001 §9.1.

### Forward-compatibility warnings (not failures unless `--strict`)

16. **Spec minor recognized.** `specMinor` is in {0, 1, 2}. Higher minors are valid per §11.1 but indicate this suite hasn't been updated to that spec.
17. **All property IDs known.** Every property ID in the file is declared in the property table. Unknown IDs indicate forward-compatibility with a future spec minor; the value is still skippable via the wire-type tag table.
18. **Profile feature flags known.** Every flag in `Profile.features` is one of the canonical set. Unknown flags are forward-compat; Strict consumers refuse, Lenient consumers warn.

## Output

The suite produces a per-file report with one line per check, marked `PASS`, `FAIL`, or `WARN`. Files conformant if every required check passes. `--strict` escalates warnings to failures.

Sample output (passing file):

```
[cube.lavs] (1174 bytes, spec 1.0)
  PASS  magic                        LAVS header confirmed
  PASS  decode                       8 scene objects, edition block CRC valid
  PASS  spec-major                   major = 1 (must be 1 for LAVS-001 files)
  PASS  spec-minor                   minor = 0 (this suite recognizes 0, 1, 2)
  PASS  crc32                        CRC32 footer matches edition block bytes
  PASS  fast-path-consistency        fast-path reader returns identical metadata to full decode
  PASS  profile-first                Profile (type 1) is the first scene object
  PASS  artboard-second              exactly one Artboard, immediately after Profile
  PASS  property-ids-known           every property ID in the scene is declared in the property table
  PASS  mesh-refs                    every Mesh refs a valid Buffer + Material
  PASS  palette-pin                  all PalettePin values are canonical or valid custom hex
  PASS  edition-required-fields      Edition has title + author + editionNumber + editionTotal + year + license
  PASS  edition-license              license = "CC-BY-4.0"
  PASS  edition-number-range         editionNumber=1/open
  PASS  signature-blob               no signature declared (RC)
  PASS  profile-features-known       features = "pbr-color"
```

Sample output (truncated file):

```
[cube-truncated.lavs] (1074 bytes)
  PASS  magic                        LAVS header confirmed
  FAIL  decode                       decoder threw: decode: EOF
  FATAL decode failed — abandoning structural checks

0/1 files conformant
```

## Running the suite

The reference suite is a TypeScript program in the `lavs-format` repository:

```bash
git clone https://github.com/guitargnarr/lavs-format
cd lavs-format
npm install
npm run conformance examples/*.lavs
```

Use `--json` for machine-readable output, `--strict` to escalate warnings.

## For implementers

If you are writing a LAVS-001 decoder in another language (Python, Rust, Go, C, etc.), the protocol for verifying your implementation:

1. Produce output structures from your decoder for each `.lavs` test file.
2. Reproduce each of the 18 checks above against your decoded output.
3. Compare your check-pass/fail per file against this suite's output on the same files.
4. Discrepancies are bugs — file an issue against the [lavs-format repository](https://github.com/guitargnarr/lavs-format/issues) or contact `editions@projectlavos.com`.

A second-party Python decoder is in development as an independent verification of cross-language portability. When complete, its output will be checked against this suite's output on the same corpus to confirm reproducibility.

## Why this suite exists

The LAVS-001 spec is published under CC BY 4.0 — anyone may implement encoders, decoders, runtimes, viewers, marketplaces, and gallery tools. Without a conformance test suite, "the spec is open" is paper-true and practice-false: there is no operational way to verify that two implementations agree.

This suite is the operational answer. An implementer who passes this suite has demonstrated agreement with the reference. Two implementations that both pass this suite agree with each other (transitively, through the spec).

The signed catalog editions published by Project Lavos LLC must pass this suite at every signing. The pre-signing RC editions on the `main` branch of `lavs-format` pass this suite as of the date above. Any future signed edition that fails this suite is, by definition, not spec-conformant — and Project Lavos LLC will not sign it.