48 lines
2.8 KiB
Markdown
48 lines
2.8 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 the
|
|
destination namespace and type immediately before it writes a private sibling
|
|
staging directory. For replacement, it moves the prior bundle to a private
|
|
sibling backup, fully reauthorizes that moved entry, checks for cancellation,
|
|
and restores it if cancellation or installing the new bundle prevents
|
|
replacement. If guarded restoration fails, the error retains the prior bundle's
|
|
recovery path.
|
|
|
|
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.
|
|
After a cleanup failure, publication inspects the sibling without masking the
|
|
original filesystem cause. Its inspectable cleanup result distinguishes a
|
|
complete recognized recovery bundle, partial remnants, an absent sibling, or
|
|
an uninspectable state. A recovery path is reported only when something
|
|
remains; only a complete recognized bundle is suitable for rollback recovery.
|
|
|
|
The application preflights before prompt inspection and collection. Publication
|
|
performs its transaction-boundary checks and final moved-destination
|
|
authorization before installation. 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).
|