Write down how a spool holds an inventory

[d-chambers]

Description

The last of the three documentation PRs planned for the inventory: the internals note, alongside notes/spool_index.qmd.

The tutorial says what an inventory contributes and the tunnel recipe works one through. Neither says when the file is read, which is most of what the attachment machinery does, and the parts worth writing down are the ones that look like bugs until the reason is stated:

• Three moments, at three times. Discovery is eager and costs a stat of each spelling; reading waits for the first question only an inventory can answer; refreshing happens when a program asks and never otherwise. So a malformed inventory cannot stop you loading data — only the inventory-backed calls fail, and they name the directory it came from.
• The decision to read is itself free. A selection settles whether it needs the inventory without touching one, because which names an inventory could state is a property of the models rather than of the document. With the corollary that a name the index already carries keeps the index's meaning, or attaching would quietly change what an existing name selects on.
• Comparison never resolves either side. Otherwise == does file I/O, comparing spools can raise out of an unreadable inventory, and the answer depends on whether something happened to read one first. The rejected alternative is stated, since that is the part a reader would otherwise wonder about.
• Read once, no modification time. The index is a cache whose truth is the files; an inventory is an input, and a file which changes under a running program is a new input rather than a stale one. Re-attaching is the refresh, which is the whole authoring loop.
• One holder, however the spool is sliced. A spool copy-constructs from its parent, so the holder is shared rather than copied — a spool sliced ten ways reads once, and two views of one parent cannot disagree about what it says.

Every claim is executed by the doc-code tests rather than asserted in prose: the page proves the reference is unread after len and get_contents, that an index-only query leaves it unread while a selection on an annotation group reads it, that editing the file changes nothing the spool holds, and that select, sort, and chunk all come back pointing at the same holder.

With this, plans/phase5-docs.md is complete: tutorial (#899), recipe (#901), note (here).

Changelog

• added: a note on inventory attachment describing when a spool reads an attached inventory, why selection can decide without reading one, and why comparison and modification times never trigger a read.

Checklist

I have:

• filled in the Changelog section above (see docs/contributing/general_guidelines.qmd).

I have (if applicable):

• referenced the GitHub issue this PR closes.
• documented the new feature with docstrings and/or appropriate doc page.
• included tests. See testing guidelines.
• added the "ready_for_review" tag once the PR is ready to be reviewed.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

@d-chambers, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 27 minutes

Limit details: You’ve used all 2 included reviews currently available under your plan.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 66182bc0-2d04-4855-a69a-fc43f7df6ddd

📥 Commits

Reviewing files that changed from the base of the PR and between 54f85a6 and bed8306.

📒 Files selected for processing (2)

• docs/notes/inventory_attachment.qmd
• scripts/_templates/_quarto.yml

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (54f85a6) to head (bed8306).

Additional details and impacted files

@@            Coverage Diff            @@
##               dev      #919   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          185       185           
  Lines        22315     22315           
=========================================
  Hits         22315     22315           

Flag	Coverage Δ
network	45.82% <ø> (ø)
unittests	100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

✅ Documentation built:
👉 Download
Note: You must be logged in to github and a DASDAE member to access the link.