37 lines
2.0 KiB
Markdown
37 lines
2.0 KiB
Markdown
# 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](../integrations/comparison-bundle.md).
|
|
|
|
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.
|
|
|
|
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](../operations.md).
|