Re: [PATCH 02/48] xfs: add log recovery item validation design document

[Dave Chinner <dgc@kernel.org>]

On Wed, Oct 14, 2026 at 04:31:17PM -0700, Darrick J. Wong wrote:
> On Tue, Oct 13, 2026 at 05:00:52PM +1100, Dave Chinner wrote:
> > Add a design document describing a systematic approach to validating log
> > items during journal recovery. Log item data read from the journal cannot
> > be fully trusted - corruption from torn writes, hardware errors or
> > software bugs can produce invalid type codes, wrong region counts,
> > truncated regions or internally inconsistent format structures that the
> > current recovery code largely uses unchecked.
> > 
> > The document describes a three-layer validation scheme (generic region
> > header decode, per-region type-specific validation, and full cross-region
> > item validation), the treatment of the transaction header as a validated
> > region type, and a set of additional safety fixes for the generic region
> > assembly code. It also lays out a phased implementation plan.
> > 
> > Changes:
> > - Add Documentation/filesystems/xfs/xfs-log-recovery-validation-design.rst
> > - Add the new document to the XFS documentation index
> > 
> > Created-by-AI: Claude Opus 4.8 (1M context)
> >
> > Prompt: Let's start by converting the existing verification doc to kernel
> > .rst format and moving it to Documentation/filesystems/xfs/ and adding it
> > to the relevant doc index file. The file should be tracked in a new patch.
> 
> Eheheh.

Yeah, I forgot this was written about 3 months ago before I
completely rewrote all the patch header generation skills. If you
read through the patch headers, you'll probably spot changes in the
way the read that coincide with refinements to the skills...

i.e. my workflow has been rapidly evolving over the past few months,
and this patch series spans quite a lot of change and refinement...

> > diff --git a/Documentation/filesystems/xfs/xfs-log-recovery-validation-design.rst b/Documentation/filesystems/xfs/xfs-log-recovery-validation-design.rst
> > new file mode 100644
> > index 000000000000..188b1bebf171
> > --- /dev/null
> > +++ b/Documentation/filesystems/xfs/xfs-log-recovery-validation-design.rst
> 
> The document sounds pretty reasonable for a first pass at hardening the
> log recovery code.  This is a good start.

OK, that's good to hear.

> <snip>
> 
> > +Layer 3: Full item validation (type-specific, cross-region)
> > +-----------------------------------------------------------
> 
> <snip>
> 
> > +Other intent/done items
> > +    similar field-level validation
> 
> But please be more specific.

Yup, it needs to be revised to match what that actually meant :)

> > +Phase 3: Full item validation
> > +-----------------------------
> > +
> > +Patch M: Add validate_item callback infrastructure
> > +    - Add the callback to the ops struct
> > +    - Call it from ``xlog_recover_reorder_trans()`` after ops verification
> > +    - Return ``-EFSCORRUPTED`` on failure, aborting recovery
> > +
> > +Patches M+1 to M+N: Implement validate_item for each item type
> > +    - Move existing validation out of ``commit_pass2`` into
> > +      ``validate_item`` where possible (e.g. ICREATE field checks)
> > +    - Add new cross-region validation
> > +    - Order: simple types first, complex types last
> > +    - INODE validation is the most complex (fork format vs region size)
> > +
> > +Phase 4: Cleanup
> > +----------------
> > +
> > +- Remove redundant validation from ``commit_pass1``/``commit_pass2`` that
> > +  is now covered by ``validate_region``/``validate_item``
> > +- Add ``ASSERT()``\ s in commit handlers to verify validation has run
> > +- Review and update error messages for consistency
> 
> Why is the plan for splitting scope across M+N patches relevant for a
> design document that will live in the kernel?

It's not. This document was derived from the original planning work
I did in the LLM. I forgot to remove this stuff once the LLM didn't
need it as a reference anymore. I'll match sure the design doc is
updated before the next version.

FWIW, the reason for writing the design/planning doc in this way was
to give the LLM something to re-reference whilst working through the
patch series. The plannig and coding wasn't all done in one session.
The work was also large enough in scope that frequent context
compaction was required to manage context size and minimise token
cache re-read costs. I simply forgot to tell it to clean up the
design doc as the work was completed.

I've since changed how I record the implementation plan for new
development - the design docs still exist for the "LLM needs
guidance" reasons, but I use LLM session memory for maintaining the
implementation plan now. Hence the LLM now automatically removes
work from the plan as it is complete, and I don't have to remember
to tell it to do so anymore. That's likely why I forgot about this
altogether...

Cheers,

Dave.

-- 
Dave Chinner
dgc@kernel.org