feat: validate DiskSage cloud capacity evidence

[seonghobae]

Description

• add authenticated POST /api/cloud-capacity-assessment/validate for the separate disksage.cloud-capacity-assessment v1 envelope
• strictly validate capacity schema v3 provider/account shapes, unsigned 64-bit arithmetic, fit/blocker/notice consistency, and redacted plan binding
• cap raw JSON at 64 KiB, reject duplicate keys and unknown fields, and return only fixed contract metadata
• keep the validator database-free and explicitly separate capacity planning from per-file lineage, provider sync proof, and eviction authorization
• update the prior file-lineage document now that the separate contract exists

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Validation

• python3 -m pytest -q tests/test_cloud_capacity_assessment_api.py (26 passed)
• python3 -m pytest -q tests/test_cloud_capacity_assessment_api.py tests/test_file_lineage_api.py (87 passed)
• python3 -m ruff check services/cloud_capacity_assessment.py api/cloud_capacity_assessment.py tests/test_cloud_capacity_assessment_api.py main.py
• live DiskSage release stdout from read-only iCloud capacity export accepted by this validator with valid=true

Trust boundary

This endpoint validates schema and submitted claim consistency only. It does not authenticate the upstream provider response, revalidate freshness, persist quota, execute provider writes, prove sync, or authorize local-source eviction.

Research grounding

• W3C PROV Overview and PROV Constraints distinguish provenance consistency from external trust.
• Missier, Belhajjame, and Cheney, EDBT 2013, doi:10.1145/2452376.2452478, is cited rather than redistributed.
• Provider shapes follow current Microsoft Graph drive/quota and Google Drive About references.

Stack

Based on #1132. Producer: ContextualWisdomLab/disksage#86, based on disksage#85.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[coderabbitai]

Important

Review skipped

Draft detected.

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: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c7c719d2-4948-4cf6-8615-00772f01c23e

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

---

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

[github-actions]

PR governance metadata gate is not ready for 1eff96ac1ec047b339eb26f61e0586fb9816dfc0:

• Draft PR: merge automation is paused.

[seonghobae]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[seonghobae]

Local current-head security evidence (2026-07-29 KST):

• GitHub merge ref 3c1a8a2 (base 512e13a + head 5ab67d8)
• Bandit: 32,582 backend LOC, 0 findings at all severities
• diff check: clean
• fresh Trivy 0.71.1 DB, repo-wide vuln+secret+misconfig, HIGH/CRITICAL, fixable-only: the PR files/backend are clean; 6 HIGH dependency findings come from the stale stacked base frontend lockfile (Next.js 4, PostCSS 1, Sharp/libvips 1)
• live develop 237f917 was scanned with the same DB/options and is clean (0 vulnerabilities, secrets, misconfigurations)

This PR deliberately does not duplicate the already-merged dependency updates. The central Security Scan must be rerun after the stacked base is brought forward. Draft/governance failure remains expected until then.

[seonghobae]

Stacked child PR #1182 adds the DiskSage metadata-first semantic catalog candidate-batch validation contract after this capacity-assessment layer. It is database-independent and does not authorize copy or eviction.

[seonghobae]

Closing as draft-abandoned: incomplete DiskSage contract work not ready for commercial pilot merge; reopen when evidence-backed and non-draft. Loop drain 2026-07-31.