7.0 KiB
7.0 KiB
Phase 14.1: cloud-local-file-parity-hardening - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents. Decisions are captured in CONTEXT.md - this log preserves the alternatives considered.
Date: 2026-06-26 Phase: 14.1-cloud-local-file-parity-hardening Areas discussed: Open/view/download parity, Analyzed metadata display, Retry/reanalyze states, Unsupported/provider-limited actions, Parity tests
Open/view/download parity
| Question | Options Considered | User's Choice |
|---|---|---|
| How should cloud file open/view behave when a cloud file has been analyzed? | Route to a document-like detail view; keep direct open/download; hybrid explicit View analysis; other | Route to a document-like detail view backed by CloudItem, not a local Document import. |
| What should happen for a cloud file that has not been analyzed yet? | Open/preview first with analyze prompt; always show detail view; split by file type; other | Always show the detail view; if not analyzed, offer Analyze. After analysis, fill the view with extracted text/topics/status. Rename Re-classify to Re-analyze everywhere. |
| For preview and download from that cloud detail view, how should the controls behave? | Mirror local detail controls; keep separate cloud labels; preview embedded/download secondary; other | Mirror local detail controls and placement, using authorized cloud preview/download handlers. |
| How should the app distinguish cloud files from local files on the detail view? | Subtle source metadata; strong cloud banner; breadcrumbs only; other | Use subtle provider/location/status metadata. |
Notes: User wants the cloud detail view to be the main file-open target even before analysis, not just a post-analysis route.
Analyzed metadata display
| Question | Options Considered | User's Choice |
|---|---|---|
| What should the cloud detail view show once analysis has completed? | Same sections as local documents; compact summary first; cloud-specific panel; other | Same sections as local documents. |
How should analyzed cloud files appear in StorageBrowser.vue rows/cards? |
Match local rows/cards where data exists; status badge only; separate cloud indicators; other | Match local rows/cards where equivalent data exists. |
| How should stale cloud analysis be presented when provider version/etag changed? | Show stale state with Re-analyze; hide stale analysis; treat stale as failed; other | Keep prior extracted text/topics visible, mark stale, and offer Re-analyze. |
| If cloud analysis partially succeeds, what should the UI show? | Show available data with targeted retry; failed state only; queue-only failure; other | Show available partial data and mark failed classification/topics with targeted retry/Re-analyze. |
Notes: Prior data should remain useful even when stale or partially failed.
Retry/reanalyze states
| Question | Options Considered | User's Choice |
|---|---|---|
| Where should the Re-analyze action appear? | Same places local re-analysis appears plus cloud detail; detail only; queue only; other | Same local/cloud detail and row action locations when analysis exists or is stale/failed. |
| What should Re-analyze do for an already-current analyzed cloud file? | Force fresh analysis after confirmation; keep idempotent skip; only reclassify existing text; other | Force fresh extraction/classification after confirmation. |
| How should failed analysis retries behave from detail view or row/card? | Retry as part of existing job model; always create new job; queue only; other | Use existing job retry semantics where possible; create a single-item retry job when no active job exists. |
| How should local document wording change alongside cloud parity? | Rename only action label; rename action and internal API/code; cloud only; other | Rename visible Re-classify copy to Re-analyze everywhere while preserving existing behavior/API unless planning requires internal rename. |
Notes: The label change applies globally to visible UI copy.
Unsupported/provider-limited actions
| Question | Options Considered | User's Choice |
|---|---|---|
| How should unsupported cloud preview/download/analyze cases appear in shared UI? | Shared disabled/typed state; hide unavailable actions; cloud warning panel; other | Same shared action positions, disabled or typed with backend-provided reasons. |
| When cloud format cannot be previewed but can be downloaded, what should happen? | Show preview unavailable and keep Download active; auto-download fallback; hide Preview; other | Show preview unavailable and keep authorized Download active. |
| If a provider cannot supply reliable version/etag metadata, how should states behave? | Use fallback fingerprint and label uncertainty subtly; always require manual Re-analyze; hide freshness; other | Use fallback fingerprint; surface uncertainty only when it affects a user action. |
| If analysis is unsupported for a file type, where should that be shown? | Everywhere Analyze would appear; detail only; queue/estimate only; other | Everywhere the Analyze action would appear, disabled with the same reason text. |
Notes: Unsupported preview must not trigger an automatic download from Preview.
Parity tests
| Question | Options Considered | User's Choice |
|---|---|---|
| What should be the core frontend parity test shape? | Paired local/cloud assertions; cloud-only regression tests; E2E browser flow only; other | Paired local/cloud assertions in shared components and detail surfaces. |
| Which backend security/cache invariants must be explicit? | All cache/auth boundaries; only new detail endpoints; reuse Phase 14 coverage; other | Cover no provider URL/credentials/object_key leakage, owner/admin negatives, cache hydration, forced Re-analyze path, and no provider mutation. |
| Should tests require a new cloud-file detail route? | Yes, route-level parity; component parity only; no route tests; other | Yes, route-level parity from browser row to cloud detail route. |
| How broad should live/provider-style coverage be? | Mocked provider contracts plus existing opt-in live pattern; live tests for every provider; frontend-only provider coverage; other | Mocked providers for deterministic tests and preserve opt-in live tests only where existing patterns support them. |
Notes: The test contract should force local/cloud parity rather than allowing a cloud-only UI fork.
Codex's Discretion
- Choose exact route naming/path, shared detail component shape, source metadata presentation, and internal naming changes where necessary.
- Keep local/cloud parity and provider ownership boundaries as the deciding constraints.
Deferred Ideas
- Unified smart search remains Phase 15.
- Provider change tracking and broader sync reliability remain Phase 16.
- Permanent local import/pinning remains future
IMPORT-01. - Live parity testing for every provider is out of scope.