Conventions

def archive_blob(checksum: str) -> str:
    """
    Get the blob path for a file in the archive.

    Layout: archive/5a/6a/cf/5a6acf229ba576d9a40b09292595658bbb74ef56/blob

    Args:
        checksum: SHA256 checksum of file
    """
    return f"{archive_prefix(checksum)}/{ARCHIVE_BLOB}"

def archive_meta(checksum: str, file_id: str) -> str:
    """
    Get a file metadata path for a specific file instance.

    Multiple files with the same checksum but different source paths
    each get their own metadata file, keyed by their File.id.

    Layout: archive/5a/6a/cf/.../file-abc123.json

    Args:
        checksum: SHA256 checksum of file
        file_id: The File.id (hash of source path + checksum)

    Raises:
        ValueError: If ``checksum`` or ``file_id`` is malformed.
    """
    safe_name(file_id, "file_id")
    return f"{archive_prefix(checksum)}/{file_id}.json"

def archive_prefix(checksum: str) -> str:
    """
    Get the directory path for a file in the archive.

    Layout: archive/5a/6a/cf/5a6acf229ba576d9a40b09292595658bbb74ef56/

    Args:
        checksum: SHA256 checksum of file
    """
    return f"{ARCHIVE}/{make_checksum_key(checksum)}"

def archive_txt(checksum: str, origin: str) -> str:
    """
    Get a file text content path for a specific extraction origin.

    Multiple text extractions can exist per file, keyed by origin
    (e.g., different OCR engines or extraction methods).

    Layout: archive/5a/6a/cf/.../{origin}.txt

    Args:
        checksum: SHA256 checksum of file
        origin: The extraction origin/engine name

    Raises:
        ValueError: If ``checksum`` or ``origin`` is malformed.
    """
    validate_origin(origin)
    return f"{archive_prefix(checksum)}/{origin}.txt"

def documents_diff(ts: datetime | None = None) -> str:
    """
    Get path for a documents diff export file.

    Layout: diffs/exports/documents.csv/{ts}.diff.csv

    Args:
        ts: Compact timestamp (YYYYMMDDTHHMMSSZ), defaults to current time

    Returns:
        Path to diff file
    """
    if ts is None:
        ts = utc_now()
    ts_iso = ts.strftime(TS_FORMAT)
    return f"{DIFFS_DOCUMENTS}/{ts_iso}.diff.csv"

def entities_diff(ts: datetime | None = None, suffix: str | None = None) -> str:
    """
    Get path for an entities diff export file.

    Layout: diffs/entities.ftm.json/{ts}.delta.json

    The delta file contains line-based JSON with operation envelopes:
        {"op": "ADD", "entity": {"id": "...", "schema": "...", "properties": {...}}}
        {"op": "MOD", "entity": {"id": "...", "schema": "...", "properties": {...}}}
        {"op": "DEL", "entity": {"id": "..."}}

    Args:
        ts: Compact timestamp (YYYYMMDDTHHMMSSZ), defaults to current time

    Returns:
        Path to delta file
    """
    if ts is None:
        ts = utc_now()
    ts_iso = ts.strftime(TS_FORMAT)
    path = f"{DIFFS_ENTITIES}/{ts_iso}.delta.json"
    if suffix:
        path = f"{path}.{suffix}"
    return path

def entity_shard(entity_id: str, shards: int) -> str:
    """Hex shard key for an entity id under a uniform shard count.

    Uses the first 8 hex chars of the entity_id hash, taken mod ``shards``,
    then zero-padded to ``shard_hex_width(shards)``.
    """
    if shards <= 1:
        return "0"
    bucket = int(hash_data(entity_id)[:8], 16) % shards
    return f"{bucket:0{shard_hex_width(shards)}x}"

def lock(*parts: str, tenant: str | None = TENANT) -> str:
    """Generate a path to store a lock"""
    return join_relpaths(LOCKS, tenant or TENANT, *parts)

def mapping(content_hash: str) -> str:
    """
    Get the mapping.yml path for the given file SHA256.

    Layout: mappings/{content_hash}/mapping.yml
    """
    return f"{MAPPINGS}/{content_hash}/{MAPPING}"

def shard_hex_width(shards: int) -> int:
    """Hex width required to represent `shards-1` (zero-padded).

    Examples: 1→1, 8→1, 16→1, 32→2, 256→2, 4096→3.
    """
    if shards <= 1:
        return 1
    return max(1, ((shards - 1).bit_length() + 3) // 4)

def statement_origin(origin: str) -> str:
    """
    Get path prefix for given origin, following parquet partition pattern

    Args:
        origin: The origin, or phase, or stage

    Raises:
        ValueError: If ``origin`` is malformed.
    """
    validate_origin(origin)
    return f"{STATEMENTS}/origin={origin}"

def tag(*parts: str, tenant: str | None = TENANT) -> str:
    """Generate a path to store a tag"""
    return join_relpaths(TAGS, tenant or TENANT, *parts)

def version(name: str, ts: str | None = None) -> str:
    """
    Get a versioned snapshot path for a file, e.g. for index.json or config.yml

    Layout: versions/YYYY/MM/{TS_FORMAT}/<name>

    Args:
        name: The file name to version (e.g. "config.yml", "index.json")
        ts: ISO timestamp, omit to use current time

    Returns:
        Path like "versions/2025/01/20250115T103000/config.yml"
    """
    if ts is None:
        ts = utc_now().strftime(TS_FORMAT)

    year = ts[:4]
    month = ts[4:6]
    return f"{VERSIONS}/{year}/{month}/{ts}/{name}"

def statements_partition_optimized(shard: str, bucket: str, origin: str) -> str:
    """Per-partition freshness tag: a ``(shard, bucket, origin)`` was merged.

    Partition-scoped analog of :data:`STATEMENTS_OPTIMIZED`, stamped by
    :meth:`ParquetStore.merge` after it rewrites the partition. See
    :func:`statements_partition_updated` for the freshness comparison.

    Args:
        shard: Hex-padded shard value.
        bucket: FtM schema bucket (``thing`` / ``interval`` / ...).
        origin: Source tag – validated so it stays a single path segment.
    """
    validate_origin(origin)
    return f"statements/{shard}/{bucket}/{origin}/last_optimized"

def statements_partition_updated(shard: str, bucket: str, origin: str) -> str:
    """Per-partition freshness tag: a ``(shard, bucket, origin)`` was written.

    Partition-scoped analog of :data:`STATEMENTS_UPDATED`, stamped by
    :meth:`ParquetStore.append`. :meth:`ParquetStore.merge` compares it
    against :func:`statements_partition_optimized` via
    :meth:`TagStore.is_latest` to skip partitions that haven't changed
    since their last merge.

    Args:
        shard: Hex-padded shard value.
        bucket: FtM schema bucket (``thing`` / ``interval`` / ...).
        origin: Source tag – validated so it stays a single path segment.
    """
    validate_origin(origin)
    return f"statements/{shard}/{bucket}/{origin}/last_updated"