docs(site-memory): distinguish entry expiry from backing-file cleanup

[senamakel]

The SiteMemoryHost contract currently describes expiry without distinguishing entry freshness from physical backing-file cleanup. Clarify that TinyComputer owns each plan or hint's 30-day freshness, while hosts may reclaim unchanged backing files on periodic maintenance outside Load requests.

This changes Rustdoc only: no wire members, data, versions, or runtime behavior change.

Refs senamakel/openhuman#27
Part of tinyhumansai/openhuman#8056

Validation:

• cargo fmt --all -- --check
• cargo check -p tinycomputer-bus
• cargo clippy -p tinycomputer-bus --all-targets -- -D warnings
• cargo test -p tinycomputer-bus: 232 unit tests and 34 doctests passed
• cargo doc -p tinycomputer-bus --no-deps: no warnings
• git diff --check
• Independent source review passed at 9d0f6f0

[tinysweeper]

Tiny Sweeper review

Tiny Sweeper completed its review; deterministic results follow.

State: Ready for maintainer review
Priority: none
Reviewed head: 9d0f6f0213f2
Updated: 2026-10-17T03:41:36Z

Review snapshot

Change surface	Files	Review signal	Count
Production	1	Active findings	0
Tests	0	Noted findings	0
Documentation	0	Resolved findings	0
Configuration	0	Pending checks/questions	0

Completeness: Complete
Test assessment: No supported feature-to-test mapping was available; this does not mean tests are absent or passed.

What changed

The rustdoc block of `crates/tinycomputer-bus/src/site_memory/mod.rs` now states that the host owns where the bytes live, that the reuse rules, fact-value filtering and per-plan/per-hint 30-day freshness belong to the module, and adds a paragraph stating a host may remove unchanged backing files as physical storage maintenance outside `Load` requests, independent of the module's per-plan and per-hint freshness rules. No executable code is touched.

Features

• Modified — Module documentation distinguishing entry freshness from host-side backing-file cleanup: Clarifies for host implementers that 30-day freshness and reuse/fact filtering are module-owned while reclamation of unchanged files is host storage maintenance to be scheduled outside `Load`; no runtime behaviour changes. (crates/tinycomputer-bus/src/site_memory/mod.rs)

Tests

No supported feature-to-test mapping was produced. Test execution is not inferred.

Findings

No active actionable findings.

Before merge

None.

How this fits together

flowchart LR
  n0["SiteMemory"]:::impacted
  n1["LoadSiteResponse"]:::impacted
  n2["SaveSiteRequest"]:::impacted
  n3["SavedPlan"]:::impacted
  n4["save"]:::impacted
  n0 -->|uses| n3
  n1 -->|uses| n0
  n2 -->|uses| n0
  n4 -->|uses| n0
  n4 -->|uses| n2
  classDef changed fill:#0d4429,stroke:#238636,color:#e6edf3
  classDef impacted fill:#161b22,stroke:#6e7681,color:#c9d1d9
  classDef flagged fill:#5a1e02,stroke:#d93f0b,color:#ffffff
  classDef blocking fill:#67060c,stroke:#f85149,color:#ffffff

Loading

Agent review details

critique

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Positive: Review found no defect reachable from this diff; the documented per-plan and per-hint 30-day expiry matches `expire`/`KEEP_SECS` applied off each record's own `ok_at`.
• Lane summary: Documentation-only change to the `site_memory` module header: it restates that tinycomputer-core::sites owns reuse, fact filtering and each plan's or hint's 30-day freshness, and adds a note that a host may clean up unchanged backing files independently of those rules. Both statements match the implementation I can see — `expire` in `tinycomputer-core::sites` applies `KEEP_SECS` per plan and per hint off each record's own `ok_at`, and a missing or refused memory is already documented as costing the task nothing but the memory — so no code behaviour changes and I found no defect reachable from this diff. _The code index is behind this pull request (indexed at `28121790dd63`), so retrieved context may be out of date._

security

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Positive: No code, signatures, dependencies or permissions change, so the diff introduces nothing that can fail or misbehave for any input.
• Lane summary: The change is documentation only: it rewrites the module doc to say the host owns where the bytes live, describes per-plan and per-hint 30-day freshness, and notes that a host may delete unchanged backing files outside `Load` requests. No code, signatures, dependencies, or permissions change, so there is nothing that can fail or misbehave for any input; no repository rule in AGENTS.md/CLAUDE.md covers doc wording or this claim. _The code index is behind this pull request (indexed at `28121790dd63`), so retrieved context may be out of date._

tests

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Lane summary: The diff is documentation only — module rustdoc wording in `crates/tinycomputer-bus/src/site_memory/mod.rs`, clarifying who owns freshness rules and noting that host-side file cleanup is independent of them. It changes no behaviour, so there is nothing here for a test to pin, and no test coverage is owed; the claims about 30-day freshness already match the existing `KEEP_SECS`/`expire` implementation in `tinycomputer-core`. No findings. _The code index is behind this pull request (indexed at `28121790dd63`), so retrieved context may be out of date._

commits

• Conclusion: Neutral
• Scope reviewed: all assigned evidence
• Positive: Nothing sensitive found in what this pull request commits.
• Lane summary: Nothing sensitive found in what this pull request commits.

description

• Conclusion: Success
• Scope reviewed: all assigned evidence
• Positive: Title and body describe exactly the doc-only split of entry expiry from backing-file cleanup, and the wording agrees with the diff and with `tinycomputer-core::sites` semantics.
• Lane summary: The pull request changes only the Rustdoc block of `crates/tinycomputer-bus/src/site_memory/mod.rs`, splitting the 30-day entry freshness (owned by the module) from host-side reclamation of unchanged backing files, and the title and body describe exactly that with no wire, data or behaviour changes claimed. The wording is consistent with the `KEEP_SECS`/`expire` semantics in `tinycomputer-core::sites`, so the description and the diff agree and there is nothing to flag. _The code index is behind this pull request (indexed at `28121790dd63`), so retrieved context may be out of date._

Evidence and run details

• Models: ladder/vectors-oai3, deepseek-v4.1-flash
• Spend: $0.000187
• Tokens: 78793 input · 7561 output · 4992 cached · 66 embedding

Head	State	Pass summary
9d0f6f0213f2	ready for maintainer review	0 active finding(s), 0 resolved finding(s) (at 2026-10-17T03:41:36Z)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0b68e4df-35d9-42a9-a0cc-c06b19fa4e4c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-17T03:44:25.801315Z	9d0f6f0	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[tinysweeper]

tinysweeper found nothing blocking. Approving.

             $0.0002 · 78,793 in / 7,561 out · 4,992 cached (6%)  · ladder/vectors-oai3, deepseek-v4.1-flash · 66 embedded
critique:    $0.0000 · 13,563 in / 1,309 out · 0 cached (0%)      · deepseek-v4.1-flash
security:    $0.0000 · 13,322 in / 1,440 out · 0 cached (0%)      · deepseek-v4.1-flash
tests:       $0.0000 · 28,056 in / 1,599 out · 0 cached (0%)      · deepseek-v4.1-flash
description: $0.0001 · 22,044 in / 2,324 out · 4,992 cached (23%) · deepseek-v4.1-flash