Adds a ``cache_salt: str = ""`` field to ``ObjectKey`` and
``IPCCacheEngineKey`` so same-content/different-user cache entries
produce distinct keys. This is the data-model piece of the per-user
L2 cache quota feature (PR2 of 6). PR1a (LMCache#3029) wired cache_salt
through the adapter surface but left it a no-op until the data model
landed; this PR makes it load-bearing.

Key changes:

- ``ObjectKey`` and ``IPCCacheEngineKey`` gain ``cache_salt`` field
  participating in eq/hash. ``__post_init__`` on both rejects ``@`` in
  the salt — this is the invariant the L2 adapter parsers rely on.
- ``ipc_key_to_object_keys(ipc_key, chunk_hashes)`` reads
  ``ipc_key.cache_salt`` internally. No separate parameter, so callers
  cannot accidentally drop the salt.
- Native connector, FS adapter Python, and FS adapter C++ all use a
  leading ``@@`` marker to disambiguate salted from legacy keys. Legacy
  files and wire payloads (empty salt) remain readable — existing
  stored data is preserved.
- msgspec encodes dataclasses as maps, so an old 7-field
  ``IPCCacheEngineKey`` payload decodes on new code with ``cache_salt``
  defaulting to ``""``. New-on-old works because msgspec ignores
  unknown map keys by default.

Tests: 32 new cases covering serialization roundtrip (native + FS),
validation (``@`` rejection), isolation semantics (eq/hash per salt),
msgspec wire compat (old→new, new→new), and the FS C++ parser's
legacy/salted/``@``-in-model paths.

Signed-off-by: royyhuang <roy.y.huang@gmail.com>

Addresses review feedback on LMCache#3042:

- cache_salt must not contain '/', '\', or NUL (in addition to '@').
  The FS adapter embeds salt into filenames — '/' would inject directory
  separators; '\' is a Windows path separator; NUL terminates C strings
  in the C++ connector.
- Max length capped at 128 chars to stay within NAME_MAX (255) after
  model_name, kv_rank, chunk_hash, and the .data extension are added.
- Updated example external connector template
  (examples/lmc_external_native_connector) to handle the @@ salted
  key format, matching the in-tree csrc/storage_backends/fs/connector.cpp.
- Added tests for /, \, NUL rejection and length cap on both ObjectKey
  and IPCCacheEngineKey.

Signed-off-by: royyhuang <roy.y.huang@gmail.com>

All new writes use the unified @@-prefixed format for both salted and
unsalted keys:

    @@<cache_salt>@<model>@<rank>@<hash>

For empty cache_salt this becomes @@@model@rank@hash. The legacy
3-field format (no @@ prefix) is still readable by all parsers for
backward compatibility but emits a deprecation warning on the FS
adapter read path. Re-storing a legacy entry automatically migrates
it to the new format.

This simplifies parsing — the @@ prefix is always present so there
is no need to disambiguate based on field count (model_name may
contain @ and would otherwise be ambiguous).

Updated Python (native_connector + fs_l2_adapter), C++ (in-tree
fs/connector.cpp), and the example external connector template.
Tests updated: serialization format assertions reflect the @@@
prefix for empty salt, and roundtrip tests verify the parser still
handles legacy filenames.

Signed-off-by: royyhuang <roy.y.huang@gmail.com>

…-model

Supersedes the prior ``@@``-prefix design (commit 5afd493). The new
format appends ``cache_salt`` as a trailing 4th field only when set,
so un-salted keys use the original 3-field shape unchanged:

    Unsalted: <model>@<rank>@<hash>          (== pre-cache_salt format)
    Salted  : <model>@<rank>@<hash>@<salt>

Benefits over ``@@`` prefix:

- **No migration needed** for existing un-salted cache directories or
  remote stores — the on-disk/wire shape is bit-identical to before.
  The migration helper script is removed accordingly.
- **Simpler parser**: one ``split('@')`` dispatched by field count
  (3 or 4). No prefix check, no rsplit.
- **Cleaner filenames**: no triple-``@`` prefix for empty salt.

Disambiguation now relies on forbidding ``@`` in ``model_name``
(added to ``ObjectKey.__post_init__`` alongside the existing
``cache_salt`` invariants). HuggingFace model IDs use ``-_./`` so
this rejects nothing that occurs in practice.

Files updated:
- lmcache/v1/distributed/api.py  (reject '@' in model_name)
- lmcache/v1/distributed/l2_adapters/fs_l2_adapter.py
- lmcache/v1/distributed/l2_adapters/native_connector_l2_adapter.py
- csrc/storage_backends/fs/connector.{cpp,h}
- examples/lmc_external_native_connector/csrc/connector.cpp
- tests/v1/distributed/test_{fs_l2_adapter_keys,native_connector_l2_adapter}.py
- docs/design/.../l2_per_user_quota.md

Signed-off-by: royyhuang <roy.y.huang@gmail.com>

``ObjectKey.__post_init__`` now validates ``model_name`` and
``cache_salt`` invariants (no ``@``, no path separators, length cap)
and raises ``ValueError`` on violation. The previous
``_filename_to_object_key`` constructed the ``ObjectKey`` outside the
try/except block, so a stray file on disk with a forbidden character
in its parsed fields would propagate an uncaught exception —
callers (e.g. startup directory scans) expect ``None`` per the
function's contract.

Move the ``ObjectKey(...)`` construction inside the try block so the
``ValueError`` is caught and ``None`` returned. Added a test
exercising the over-length-salt path.

Signed-off-by: royyhuang <roy.y.huang@gmail.com>