Verify published config fragment bytes after rename

When to use

Use this when you already follow ownership and expected-byte gating, temp-then-rename publish, and optional publish-gate timing on an application-owned configuration fragment. This skill covers only the post-publish verification pass: proving the published name now holds the intended replacement bytes immediately after rename returns.

Reach for this when callers must not treat rename success alone as proof of publication, when silent partial publish would corrupt downstream baselines, or when orphan attempt temps must be detected before the next operation starts.

Assumes

The caller already:

• Validates ownership and expected bytes before writing a same-filesystem temp.
• Sets temp ownership and mode to match the application contract.
• Publishes with a single same-filesystem rename after gates pass.
• Retains the exact intended replacement bytes or digest computed for the temp write.

Adjacent guidance covers pre-rename gates, descriptor binding, and writer-serialization limits. This skill does not repeat those steps.

The failure it prevents

Rename returning success does not guarantee readers will observe the replacement bytes at the managed name:

1. The rename updated a directory entry, but a concurrent actor replaced the name again before verification ran.
2. The temp held the correct bytes, yet rename targeted a different managed name than the one verified.
3. An attempt-owned sibling temp remains beside the published fragment, inviting a later mistaken publish or stale baseline capture.
4. A caller records a fresh baseline from memory instead of from the published file, masking a mismatch.

Reasoned example (not an executed test): an agent renames temp to managed/overlay.toml, receives success, and immediately records a baseline from the in-memory replacement buffer. A racing hot-reload had already rewritten the fragment to different bytes between rename and baseline capture. Downstream operations believe they hold the published baseline while the file on disk differs.

Procedure

1. Keep the intended replacement fixed. The bytes or digest compared at verification time are the same material written to the temp for this attempt. Do not substitute a recomputed or normalized variant unless the temp write used that exact form.

1. Re-open the published name with no-follow semantics. Open the managed fragment relative to the managed directory when the contract allows. If the final component is a symlink, fail closed. Do not reuse a descriptor opened before rename.

1. Run a lightweight ownership gate on the open descriptor. Confirm regular-file type, expected owner identity, and mode still match the application contract. A type or ownership surprise after rename indicates the wrong entry was published or the name was substituted.

1. Read raw bytes from the same descriptor and compare to the intended replacement. Compare exact bytes or a digest computed with the same algorithm used for baselines elsewhere in the flow. Confirm total bytes read equals the size reported by fstat on this descriptor unless the contract allows sparse files.

1. Confirm the attempt temp is gone. The temp inode used for this attempt must no longer exist at its create path. An remaining attempt temp means publish cleanup is incomplete and the next operation may pick the wrong source.

1. On verification success, record the observed bytes as the new baseline. Capture from this fresh read, not from memory alone, so the next operation starts from what readers can actually open.

1. On verification failure, fail closed.

• Surface a publish-verification mismatch outcome.
• Do not start another rename in the same attempt.
• Do not invent rollback by writing guessed prior bytes.
• Do not record a fresh baseline from memory or from the failed read unless the contract explicitly defines recovery.
• Escalate for operator or application recovery; the on-disk state is now ambiguous relative to the intended replacement.

What this does not provide

• Not a substitute for pre-rename gates. Verification after rename cannot undo a publish that overwrote newer content. Publish gates and fail-closed abort policy remain required.
• Not crash-durability proof. This pass confirms byte identity at verification time. Whether the directory entry survives a host crash belongs in separate durability guidance.
• Not writer compare-and-swap. Two writers can still race; verification only detects that the name you checked does not hold your intended bytes.

Failure policy

• Never skip post-publish verification because rename returned success.
• Never treat in-memory replacement bytes as the new baseline without a matching read from the published name.
• Never delete or overwrite the published fragment to "roll back" when verification fails unless an explicit recovery contract authorizes it.
• Never ignore a surviving attempt temp after a purportedly successful publish.

Claims and evidence

The verification sequence follows from standard reasoning that directory rename success is necessary but not sufficient for proving observable content at the managed name. The hot-reload baseline mismatch timeline is a reasoned example only; no filesystem or concurrency tests were executed for this skill.