FileArtifactService

An ArtifactService that persists artifacts on the local filesystem.

The on-disk layout mirrors the other ADK file-backed artifact services so the same directory can be opened interchangeably across language ports. Each artifact version is a directory holding the raw payload (named after the artifact's basename) plus a metadata.json sidecar:

<baseDir>/users/<userId>/sessions/<sessionId>/artifacts/<artifactPath>/versions/<v>/<basename>
<baseDir>/users/<userId>/sessions/<sessionId>/artifacts/<artifactPath>/versions/<v>/metadata.json
<baseDir>/users/<userId>/artifacts/<artifactPath>/versions/<v>/<basename>            # user-scoped

An artifact is user-scoped when the session id is null or the filename starts with user: (the prefix is stripped from the path and preserved in metadata). <artifactPath> is derived from the filename, so nested names such as images/photo.png create nested directories; absolute paths and names that traverse outside the storage scope (e.g. ../secret) are rejected.

Versions are 0-based and increase monotonically. A version is published atomically by staging its payload and metadata in a temporary directory and renaming it into place, so concurrent readers only ever observe complete versions (payload and metadata together). Writes to the same artifact are additionally serialized by an in-process per-artifact lock; this does not coordinate across separate OS processes.

This impl lives in commonJvmAndroidMain because it only needs java.io.File, so the same code serves both Android and the JVM. On Android, prefer the fromContext factory (in the androidMain source set) which roots baseDir at the app-specific external files directory.