fix(docs): contract-compliant BlobAttachment + defensive read + heal 16 malformed rows (T11262)

[kryptobaseddev]

Summary

Fixes the live cleo docs fetch/cleo docs list failure (E_INTERNAL: Cannot read properties of undefined (reading 'split')) that made canonical docs unreachable for any blob attachment written by docs-update.ts. Roots out the writer/reader contract drift and heals the 16 malformed rows already in the wild.

This unblocks the Gen-7 substrate saga (T11242), whose own research docs were unreachable via the canonical CLI surface.

Root cause

• Reader (docs-read-model.ts:799): att.storageKey.split('/') threw when storageKey was undefined. Because resolveAllFromTasksDb() iterates eagerly, a single malformed row poisoned project-scope list ops.
• Writer (docs-update.ts): emitted a non-contract BlobAttachment shape ({kind, name, mime, size, blobId}) instead of the contract {kind, sha256, storageKey, mime, size} from packages/contracts/src/attachment.ts. The Zod validator existed but was never invoked at write time.

Changes

• Defensive read at docs-read-model.ts — survives malformed/legacy rows.
• Contract-compliant writer at docs-update.ts — emits sha256 + computed storageKey.
• Zod chokepoint at attachment-store.ts::put — validates the full discriminated union (all 5 attachment variants) on every write, so future drift fails fast at the source.
• Heal script scripts/heal-malformed-blob-attachments.mjs — one-shot, idempotent; healed 16 NULL-storageKey rows.
• Contract test docs/__tests__/blob-attachment-contract-T11262.test.ts — 5 cases (writer emit, legacy reject, empty-string reject, JSON round-trip, defensive read).

Validation (all pass)

1. cleo docs fetch db-substrate-pglite-vision-2026-05-28 → success, 18900 bytes
2. cleo docs list --type research → success, 50 rows
3. cleo docs list --task T11242 → success, 4 attachments
4. Heal script: Healed 16 rows then Healed 0 rows (idempotent)
5. New unit test 5/5 pass
6. pnpm biome check clean
7. pnpm --filter @cleocode/core run build clean
8. pnpm --filter @cleocode/core run test docs — 5/5 new tests pass; no new failures (42 pre-existing E_PROJECT_NOT_FOUND harness failures on main are unrelated, confirmed by stash-and-rerun)

Notes

• 2473 legacy storageKey:'' rows don't break reads (empty string has .split); they heal-on-next-write through the chokepoint.
• Closes T11262 (E9 of saga T11242).

🤖 Generated with Claude Code