kite/.planning/phases/13-virtual-local-cloud-operations/13-06-PLAN.md

phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
13	06	execute	4	13-05	backend/api/cloud/operations.py backend/services/cloud_operations.py backend/services/cloud_items.py backend/tests/test_cloud_mutations.py backend/tests/test_cloud_audit.py	true	CLOUD-03 CLOUD-09	truths artifacts key_links Successful cloud upload does not return before authoritative metadata reconciliation completes. Upload success writes metadata-only audit rows, while skipped, canceled, or failed queue decisions stay silent. Upload freshness and navigation updates still route through `cloud_items.py` rather than a second reconcile path. path provides backend/services/cloud_operations.py Authoritative upload success handling that routes back through centralized reconciliation and audit helpers. path provides backend/services/cloud_items.py Stable folder freshness and item identity updates after upload success. from to via pattern authoritative upload success cloud_items reconciliation service-layer follow-through before response return upload from to via pattern authoritative upload success metadata-only audit rows same-transaction audit helper call cloud.item

Finish the bounded upload follow-through slice of Phase 13: reconcile successful uploads immediately, refresh affected folder state truthfully, and emit metadata-only audit rows only on authoritative success.

Purpose: Complete CLOUD-09 for uploads before the shared frontend queue is wired to the backend. Output: Passing upload reconciliation and audit suites with no duplicate reconcile path.

<execution_context> @$HOME/.codex/gsd-core/workflows/execute-plan.md @$HOME/.codex/gsd-core/templates/summary.md </execution_context>

@AGENTS.md @.planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md @backend/api/cloud/operations.py @backend/services/cloud_operations.py @backend/services/cloud_items.py @backend/services/audit.py @backend/tests/test_cloud_mutations.py @backend/tests/test_cloud_audit.py

Artifacts this phase produces

• Upload success follow-through in backend/services/cloud_operations.py.
• Authoritative upload reconciliation and folder freshness updates through backend/services/cloud_items.py.
• Passing upload mutation and audit suites for CLOUD-03 and CLOUD-09.

Pattern analogs

• backend/services/cloud_items.py — single reconciliation and freshness authority.
• backend/services/audit.py — metadata-only audit helper used inside the caller transaction.

Task 1: Route authoritative upload success through centralized reconciliation before returning backend/api/cloud/operations.py, backend/services/cloud_operations.py, backend/services/cloud_items.py, backend/tests/test_cloud_mutations.py - backend/services/cloud_operations.py - backend/services/cloud_items.py - backend/tests/test_cloud_mutations.py - .planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md - Test 1: successful upload updates current-folder navigation through centralized reconciliation before success returns - Test 2: upload freshness state stays truthful and does not bypass `cloud_items.py` - Test 3: failed, skipped, and canceled queue decisions do not mutate listing freshness as success Feed authoritative upload success back through `backend/services/cloud_items.py` immediately, update affected folder freshness truthfully, and keep stable row identity for the newly visible item before the route returns success. Do not bypass centralized reconciliation, do not mutate quota, and do not let skipped or canceled queue decisions look like successful overwrites. - upload mutation suites pass with reconcile-before-return behavior - navigation refresh is tied to authoritative success only - upload follow-through still uses the single shared reconciliation path docker compose run --rm backend pytest -v tests/test_cloud_mutations.py -k "upload" -x Successful uploads now refresh authoritative metadata and freshness before the API reports success. Task 2: Emit metadata-only audit rows only for authoritative upload success backend/services/cloud_operations.py, backend/tests/test_cloud_mutations.py, backend/tests/test_cloud_audit.py - backend/services/cloud_operations.py - backend/services/audit.py - backend/tests/test_cloud_audit.py - .planning/phases/13-virtual-local-cloud-operations/13-CONTEXT.md - Test 1: successful upload writes metadata-only audit rows in the caller transaction - Test 2: failed, skipped, canceled, and retry-needed queue outcomes do not produce false success audit events - Test 3: audit rows never include provider URLs, tokens, bytes, or document text Write metadata-only audit rows in the same request transaction only after authoritative upload success has reconciled metadata. Preserve the Phase 13 secrecy rules by keeping provider URLs, tokens, decrypted credentials, bytes, and document content out of the audit payload. Treat Skip, Cancel all, retryable error, and conflict-pause outcomes as non-success paths that must not emit a success audit event. - upload audit suites pass - audit behavior is tied to authoritative success only - no upload audit row includes provider URLs, tokens, bytes, or document text docker compose run --rm backend pytest -v tests/test_cloud_mutations.py tests/test_cloud_audit.py -k "upload or audit" -x Upload success now satisfies the metadata refresh and metadata-only audit half of `CLOUD-09`.

<threat_model>

Trust Boundaries

Boundary	Description
upload success → metadata state	Only authoritative success may update cloud metadata or folder freshness.
upload success → audit log	Only authoritative success may write an audit row, and it must stay metadata-only.

STRIDE Threat Register

Threat ID	Category	Component	Disposition	Mitigation Plan
T-13-19	T	upload reconciliation	mitigate	Mutation tests require reconcile-before-return and forbid success-state bypasses.
T-13-20	I	upload audit payloads	mitigate	Audit suites verify metadata-only rows for successful uploads only.
T-13-21	R	queue decision logging	mitigate	Tests require Skip, Cancel all, conflict-pause, and retry-needed outcomes to avoid false success events.
</threat_model>

- Pass the upload mutation and audit suites. - Confirm every backend pytest invocation is a direct `docker compose run --rm backend pytest ...` command. - Confirm upload success routes through centralized reconciliation before audit and before response return.

<success_criteria>

• Successful uploads refresh navigation and folder freshness through the shared reconciliation layer.
• Successful uploads produce metadata-only audit rows promptly enough to satisfy CLOUD-09.
• The upload follow-through plan stays bounded to 5 files and does not absorb the frontend queue work. </success_criteria>

Create `.planning/phases/13-virtual-local-cloud-operations/13-06-SUMMARY.md` when done