paths

class FileSaveEntry(BaseModel):
    """One small file in a batch save request.

    ``path`` addresses the leaf (last component is its stem); ``extension`` is the
    bytes' actual on-disk extension (must be one the leaf's scalar declares); and
    ``data_base64`` carries the bytes themselves. The batch is for many tiny files
    — a larger file uses a single streaming ``PUT files/{path}`` instead.
    """

    path: list[str]
    extension: str
    data_base64: str

class FileSaveRequest(BaseModel):
    """Request body for the ``files:save`` batch endpoint.

    Every entry is validated against the schema before anything is written, so
    the batch either applies in full or fails with no partial write.
    """

    entries: list[FileSaveEntry]

class LeafResolveEntry(BaseModel):
    """One leaf in a batch resolve request.

    ``path`` is the chain of on-disk folder names to the leaf, its last component
    the leaf stem. ``known_version`` is the content version the client currently
    has cached, or ``None`` when it holds no copy; the server compares it against
    the leaf's current version to decide ``unchanged`` vs ``present``.
    """

    path: list[str]
    known_version: str | None = None

class LeafResolveRequest(BaseModel):
    """Request body for the ``files:resolve`` batch endpoint.

    ``results[i]`` of the response corresponds to ``entries[i]``.
    """

    entries: list[LeafResolveEntry]

class LocationModel(BaseModel):
    """A geographic position carried as request context.

    The WGS84 fields of the ``edu.cornell.location`` value
    (``altitude_meters``/``heading_degrees`` default to ``0.0``), declared in
    the ``X-CG-Location`` header's field order. A plain mirror so
    [api_models][] stays decoupled from the type system; the server converts
    it to a ``cg.Location`` at the interceptor boundary.
    """

    latitude: float
    longitude: float
    altitude_meters: float = 0.0
    heading_degrees: float = 0.0

class RequestProfileModel(BaseModel):
    """Who (and optionally where) a request comes from.

    ``user_id`` is the requesting client's identity so interceptor-backed leaves
    can resolve per-user; ``location`` is the caller's position when they have
    opted in to sharing it with this server. Built server-side from the request's
    ``X-CG-User-Id`` / ``X-CG-Location`` headers; both absent by default.
    """

    user_id: str | None = None
    location: LocationModel | None = None