SaveFilesAsArtifactsPlugin: document interaction between file_data (gs://), placeholder, load_artifacts, and session/context replay

[dfg-98]

Context

We're building on ADK with GcsArtifactService + SaveFilesAsArtifactsPlugin + LoadArtifactsTool.
Official artifacts docs say clearly that load_artifacts content is temporarily appended to the request and not permanently saved to session history:
https://google.github.io/adk-docs/artifacts/
The Google Cloud article "Manage Context Efficiently With Artifacts" recommends
SaveFilesAsArtifactsPlugin + load_artifacts so uploads are not sent to the model on every turn:
https://medium.com/google-cloud/2-minute-adk-manage-context-efficiently-with-artifacts-6fcc6683d274

Question

Since commit e3caf79, SaveFilesAsArtifactsPlugin also adds Part(file_data=FileData(file_uri=canonical_uri))
when the URI is model-accessible (gs://, https, http), in addition to the text placeholder.
Can the maintainers clarify:

1. Intended production pattern: placeholder only + load_artifacts, or placeholder + gs:// file_data, or both?
2. Session persistence: we understand file_data stores URI metadata on the event, not bytes — correct?
3. Context replay: when session history is rebuilt for turn N+1, are historical file_data parts included in generateContent again? If yes, does Vertex re-resolve the GCS URI each time (multimodal cost/latency)?
4. attach_file_reference=False: is that the supported way to get placeholder-only / load_artifacts-only behavior with GCS-backed artifacts?
5. Docs: should this be documented on https://google.github.io/adk-docs/artifacts/ (currently only LoadArtifactsTool is explained; file_data upload path is not)?

Our environment

• Vertex Gemini + GcsArtifactService (production bucket in project GCS)
• Local dev: fake-gcs-server + STORAGE_EMULATOR_HOST (local bucket names not visible to Vertex → 404 if gs:// refs are sent)

Related

• Discussion Files Processing Workflow #3846
• Issue [BUG]: Before load_artifacts, Incorrect file_uri handling for OpenAI and Claude/Anthropic providers in LiteLLM #4038, Documentation: load_artifacts tool appears required for PDF/HTML handling in Vertex AI Agent Engine #4928
• Commit e3caf79