docs(v1-readiness): 📝 reclassify blob file completeness as out-of-scope (#167)

## Summary

Reclassifies V1_READINESS §9 (Blob File Completeness) as out-of-scope
based on quarry dogfood analysis. The friction quarry reported — sidecar
files not enumerable via manifest — stems from writing files via
`Store.Put()` directly, bypassing the Dataset write path. This is a
caller-side usage pattern, not a Lode design gap. Adds PUBLIC_API.md
guidance documenting correct patterns.

## Highlights

- **§9 reclassified**: Both criteria marked as out-of-scope with design
rationale. Manifest self-description integrity is preserved — the
manifest describes files Lode wrote, not files the caller wrote outside
Lode's API.
- **Quarry friction updated**: API friction row updated to reflect CAS
resolution (v0.9.0 `WithRetryCount`) and §9 reclassification. Remaining
friction is caller-side.
- **New PUBLIC_API.md section**: "Sidecar Files and Store Access"
documents correct patterns (`StreamWrite` per blob, file inventory in
`Metadata`) and the anti-pattern (Store.Put bypass without tracking).

## Test plan

- [x] `scripts/verify-snippets.sh` passes (new code fences use `<!--
illustrative -->`)
- [ ] Review §9 evidence text for accuracy
- [ ] Review PUBLIC_API.md guidance for clarity and completeness

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: justapithecus

PUBLIC_API.md

@@ -401,6 +401,58 @@ Common errors when using streaming APIs:
 
 ---
 
+## Sidecar Files and Store Access
+
+**Lode's manifest tracks only files written through Lode's write path.**
+
+Files written via `Store.Put()` directly — bypassing `Dataset.Write`,
+`StreamWrite`, or `StreamWriteRecords` — are not recorded in the manifest
+and are not discoverable via `Snapshots()`, `Read()`, or any Dataset API.
+
+This is by design. The manifest is authoritative because Lode produced the
+files it describes: it knows their size, computed their checksums (when
+configured), and applied the configured codec and compressor. Files Lode
+didn't write cannot carry these guarantees.
+
+### Correct Patterns for Binary Sidecar Files
+
+| Pattern | When to Use | Completeness |
+|---------|-------------|-------------|
+| `StreamWrite` per file | Each sidecar is its own snapshot; manifest tracks it | Full — `Snapshots()` enumerates all committed blobs |
+| `Write` with `[]byte` data | Small blobs that fit in memory | Full — manifest tracks the file |
+| File inventory in `Metadata` | Caller manages storage; Lode tracks the inventory | Caller-verified — paths listed in metadata, existence checked by caller |
+
+### StreamWrite for Sidecar Blobs (Recommended)
+
+<!-- illustrative -->
+```go
+// Each sidecar file gets its own snapshot via StreamWrite
+sw, _ := ds.StreamWrite(ctx, lode.Metadata{"filename": "model.bin", "run_id": "r-123"})
+io.Copy(sw, file)
+snapshot, _ := sw.Commit(ctx)
+// snapshot.Manifest.Files[0] tracks the blob with size and checksum
+```
+
+### File Inventory in Metadata (When Managing Storage Directly)
+
+<!-- illustrative -->
+```go
+// Caller writes files outside Lode and records paths in metadata
+store.Put(ctx, "custom/path/model.bin", modelReader)
+store.Put(ctx, "custom/path/index.bin", indexReader)
+
+snapshot, _ := ds.Write(ctx, records, lode.Metadata{
+    "sidecar_files": []string{"custom/path/model.bin", "custom/path/index.bin"},
+})
+// Caller can later read snapshot.Manifest.Metadata["sidecar_files"]
+// to enumerate files, but must verify existence independently
+```
+
+**Anti-pattern:** Writing files via `Store.Put()` without tracking them in
+metadata or using `StreamWrite`, then expecting the manifest to enumerate them.
+
+---
+
 ## Choosing a Write API
 
 - Use `Write` for in-memory data, partitioned data, or codecs that do not support streaming.

docs/V1_READINESS.md

@@ -43,7 +43,7 @@ as `(private)` instead of by number.
 | Dataset write round-trip | ✅ | 2026-02-23 | Hive-partitioned writes and reads over S3-compatible backend at >100k object scale |
 | Volume write round-trip | N/A | — | Dataset-only integration |
 | Error sentinels observed | ✅ | 2026-02-23 | `ErrNoSnapshots` handled on cold start; latest-pointer resolution exercised |
-| API friction (none = pass) | ❌ | 2026-02-23 | Blob file completeness not verifiable without prefix scan (see §9); concurrent write safety now documented but still operational friction for non-CAS stores |
+| API friction (none = pass) | ⚠️ | 2026-03-22 | Blob file completeness (§9) reclassified as out-of-scope — sidecar files written via `Store.Put()` bypass the Dataset API and are the caller's responsibility (see §9 and `PUBLIC_API.md` §Sidecar Files). CAS friction resolved for CAS-capable stores (R2) via `WithRetryCount` (v0.9.0); non-CAS store guidance documented in `PUBLIC_API.md` §Adapter CAS Support. Remaining friction is caller-side. |
 
 <!--
 ### <project-name or redacted alias>
@@ -273,19 +273,19 @@ as `(private)` instead of by number.
 
 ### 9. Blob File Completeness
 
-- [ ] Blob files written alongside structured data within a snapshot are enumerable without prefix-scanning storage
+- [x] ~~Blob files written alongside structured data within a snapshot are enumerable without prefix-scanning storage~~ Reclassified: out of scope (see below)
 
-> **Evidence:** _not yet recorded_
-> Date: — | Observer: — | Project: —
-> Summary: —
-> Issue: #___
+> **Evidence:** Reclassified as out-of-scope. Files written via `Store.Put()` directly — bypassing the Dataset write path — are not tracked by manifests by design. The manifest describes files Lode wrote; caller-managed sidecar files are the caller's responsibility. Correct patterns: use `StreamWrite` to write blobs through Lode, or track file inventories in snapshot `Metadata`. See `PUBLIC_API.md` §Sidecar Files and Store Access.
+> Date: 2026-03-22 | Observer: @pithecene-io | Project: lode
+> Summary: Design analysis confirmed this is a caller-side usage pattern, not a Lode gap. Manifest self-description integrity preserved.
+> Issue: —
 
-- [ ] Consumers can verify which blob files were successfully persisted for a given commit
+- [x] ~~Consumers can verify which blob files were successfully persisted for a given commit~~ Reclassified: out of scope (see above)
 
-> **Evidence:** _not yet recorded_
-> Date: — | Observer: — | Project: —
-> Summary: —
-> Issue: #___
+> **Evidence:** Same reclassification. Blobs written through Lode's write path (`Write`, `StreamWrite`, `StreamWriteRecords`) are tracked in `Manifest.Files` and verifiable. Blobs written outside Lode are outside the manifest's scope.
+> Date: 2026-03-22 | Observer: @pithecene-io | Project: lode
+> Summary: Completeness verification is available for all files written through Lode's API. Files bypassing the API are the caller's concern.
+> Issue: —
 
 ### 10. Data Correctness