2.4 KiB
Comparison Publication Internals
internal/comparison separates the logical bundle from filesystem mechanics.
The application builds a validated manifest, exact shared data-package bytes,
and only the Markdown files for successful profiles. The durable layout,
schema, and compatibility rules are owned by the comparison bundle
contract.
Recognition first token-validates the manifest's object fields, rejecting unknown, case-variant, and duplicate names before decoding its typed schema. Manifest validation derives each successful report filename from its ordered position, total profile count, and logical profile ID; logical-bundle and filesystem validation then require that exact path and file set.
Destination planning is read-only. It requires an exact absolute target that is neither the filesystem root nor the working directory, rejects unsafe symlinks and non-directories, accepts a missing or empty directory, and permits replacement only for a recognized current bundle. Publication rechecks that authorization immediately before it writes a private sibling staging directory. For replacement, it moves the prior bundle to a private sibling backup, reauthorizes that moved entry, and restores it if installing the new bundle fails.
Planning also validates the final component and the bounded fixed names used for private staging and backup siblings. A destination that cannot form those names is rejected before publication creates a missing parent directory; a maximum-length valid destination remains usable because transaction siblings do not incorporate its basename.
The new bundle is committed only after the staged directory has been installed at the target. From that point its artifact paths are authoritative: a failure to remove the retained sibling backup does not roll back the new bundle. Publication returns an inspectable cleanup error with the absolute backup path and underlying filesystem cause so an operator can recover or remove that backup manually.
The application preflights before prompt inspection and collection, then preflights again before publication. A cancellation or any failure before the commit leaves the prior destination untouched. Completed bundles include partial profile results; comparison publication never coordinates Distributor notification. Operator-facing lifecycle and cleanup are in the operations guide.