ULC v1.5.0

ulc CLI v1.5.0

Download a single-file binary for your platform below. See CHANGELOG.md
at the tag for what landed in this release.

An authoring and tooling release. The workbook gains an Imperial entry side for dual-unit fields, ulc from-sheet gains a machine-readable conversion report and a draft output directory, ulc validate flags placeholder hashes left by draft conversion, and the release archive gains the unit-conversion policy document. There is no schema or taxonomy change and no computed-value change: grades, achievements, and the generated index are untouched, the builder version does not bump, and every example record and golden file is byte-identical.

For consumers

If you consume ulc validate output, one finding class is new: a record whose declared SHA-256 is the 64-zero placeholder that draft conversion stamps for a missing file now gets a source-file/placeholder-hash WARNING at that reference. Warnings never change the exit code, and no shipped example carries the placeholder, so nothing moves unless your records do. One check tightens: a workbook archive part whose claimed compression ratio sits just above 100 to 1 was accepted by the previous truncating arithmetic and is now rejected (see the validator section). Everything else is additive: new converter columns, new opt-in flags, a new document in the release archive.

If you author workbooks, dual-unit fields on the records sheet now accept either entry side. Each SI column (overall_diameter_mm, luminaire_mass_kg, linear_mass_per_foot_kg_per_m, and the rest) has an Imperial companion column (overall_diameter_in, luminaire_mass_lb, linear_mass_per_foot_lb_per_ft); author exactly one side per field and the converter computes the other, per the new conversion policy. Existing SI workbooks convert byte-identically, with one caveat: a workbook that already carries a column named with one of the ten new Imperial header names had that column silently ignored before and has it read as an authored Imperial value now, and a row filling both sides of one field is rejected with an error naming both columns, so rename or clear any such helper column before upgrading. Note that an older ulc binary ignores unrecognized columns silently, so Imperial-authored workbooks need this release's binary or newer.

The conversion policy itself is now a published document, docs/conversion-policy.md, shipped in every release archive as CONVERSION-POLICY.md: the five dual-unit families, the conversion rule each uses (one constant for four families, a fixed formula for temperature), the rounding each computed companion receives, and the rule that the authored value is always written verbatim. The PIM mapping guidance was corrected to match it: the reference converter rounds a computed length companion to at most 4 decimal places (113 mm emits 4.4488 in), and the previous guidance's significant-figures example disagreed with the shipped toolchain.

Validator

• ulc from-sheet --json emits one machine-readable conversion report on stdout: from_sheet_version (an additive-only contract, 1.0.0), cli_version, one records[] entry per record with its record_id, authoring pattern (A through D), status (written, draft, or failed), conformance_level, warnings, the output path or draft_path where a file was written, missing_index_keys naming any required index keys the builder could not derive, an error string when a record failed outside schema validation, and, for records that reached validation, findings in the same {findings, summary} shape ulc validate --json emits, plus a summary rollup. Exit codes are unchanged; the human-readable output is unchanged when the flag is absent. Angle brackets and ampersands are escaped, matching ulc scope.
• ulc from-sheet --draft-out DIR saves DRAFT records (placeholder hashes stamped under --allow-missing-files) as <record_id>.draft.json. The distinct suffix keeps a draft from ever being mistaken for a validated record; --out still receives only records that passed validation, and a run that produced drafts still exits non-zero.
• Dual-unit workbook columns accept Imperial entry: ten new records-sheet columns (overall_diameter_in, ceiling_aperture_in, recess_depth_in, connection_cable_length_in, overall_length_in, overall_width_in, overall_height_in, luminaire_mass_lb, linear_mass_per_foot_lb_per_ft, reference_length_in), one per existing SI column. The authored leaf is written verbatim; the SI leaf is computed with the same per-family constant the SI-to-Imperial direction uses, rounded to at most 4 decimal places. The provenance override columns work on the new headers exactly as on the SI ones.
• ulc validate flags a file reference whose declared SHA-256 is the 64-zero draft placeholder with a source-file/placeholder-hash WARNING at the reference's pointer, in both text and --json output; the attestation evidence references carry the same check under --verify-evidence. A locally absent file still reports INFO, and a present file that does not match still fails with an ERROR; the warning changes no exit code.
• The workbook archive compression-ratio limit is now enforced with exact arithmetic. The previous check truncated, so a part claiming at least 1 MiB uncompressed with a ratio between 100:1 and 101:1 was accepted; it is now rejected, and the error reports the ratio rounded up so the named figure always exceeds the printed limit. The 1 MiB floor below which the ratio gate does not apply is unchanged.
• The converter caches file digests for the life of a conversion run, so a family-constant document referenced by every row (the cutsheet, the warranty-conditions document) is read and hashed once instead of once per record. Missing-file behavior is unchanged: each record still reports its own warnings and draft state.

Docs

• New docs/conversion-policy.md, and the release archives now carry it as CONVERSION-POLICY.md beside the binary, README, and LICENSE.
• docs/README.md: the contents list names the new conversion-policy document.
• mappings/pim/README.md: the dual-unit section now defers to the conversion policy and its worked example matches the reference converter's rounding.
• templates/workbook/README.md: the dual-unit authoring rules cover both entry sides, and the converter-version note for Imperial columns.
• tools/validator/README.md: the from-sheet feature bullet documents the new flags, the either-side entry rule, and the complete DRAFT behavior (never written to --out, non-zero exit); the hash-verification bullet documents the placeholder warning.
• tools/validator/internal/sheet/DESIGN.md: the dual-unit sections cover both entry directions.
• README.md: the current-release version line, and the repository-structure row for docs/ names the new document.
• ROADMAP.md: the active-version heading and narrative.