fix(store): make SessionKey collisions structurally impossible

[GautamSharma99]

Summary

Replace slash-delimited composite keys in InMemorySessionStore with structural tuple keys so distinct SessionKey values can never alias because of their text contents.

• store entries and mtimes under (project_key, session_id, subpath) tuples
• list sessions by direct project/subpath field comparison
• cascade deletes by exact project/session tuple comparison
• list subkeys without prefix parsing
• count main transcripts by subpath is None
• document the component-boundary requirement for third-party adapters

Problem

The reference store previously encoded keys with raw slash joining:

"/".join([project_key, session_id, optional_subpath])

That encoding is not injective. For example, these logically distinct keys both became a/b/c:

{"project_key": "a/b", "session_id": "c"}
{"project_key": "a", "session_id": "b", "subpath": "c"}

The ambiguity affected more than direct append/load. list_sessions(), cascading delete(), list_subkeys(), and the size helper all parsed or matched string prefixes, so one collision could mix entries, hide sessions, report incorrect subkeys, and delete unrelated data.

Implementation

A private _StoreKey alias now represents the complete storage identity:

tuple[str, str, str | None]

_key_to_tuple() preserves all three fields exactly. Main transcripts use None for the omitted subpath, making them structurally distinct even from an explicitly supplied empty string.

Every operation now uses tuple fields directly:

• append(), load(), and get_entries() use exact tuple lookup
• list_sessions() compares project_key and requires subpath is None
• main-session deletion cascades only when the first two tuple fields match exactly
• targeted subpath deletion removes exactly one tuple
• list_subkeys() returns the stored third field without slicing a prefix
• size counts tuple keys whose third field is None

The summary sidecar already used (project_key, session_id) tuples, so its representation did not need to change.

Migration and compatibility

No data migration is required. InMemorySessionStore has no durable representation, every instance starts empty, and its storage dictionaries are private. There cannot be persisted old-format keys to convert after an upgrade.

The public SessionStore contract is unchanged. The SessionKey documentation now warns adapter authors to preserve component boundaries and to encode or escape components if their backend requires a composite string key.

Tests that intentionally manipulate the private _mtimes map were updated to use tuple keys, preserving their original ordering assertions instead of allowing accidental false positives.

Adversarial tests

New coverage verifies:

• the exact reported ("a/b", "c", None) versus ("a", "b", "c") collision
• independent append and load behavior
• correct main-session listing and subkey extraction
• accurate main-transcript size counting
• cascade deletion cannot remove the formerly colliding key
• targeted subpath deletion cannot remove the main transcript
• omitted subpath versus explicit empty subpath
• empty project/session components
• repeated slash sequences in every component
• Unicode project, session, and subpath values

Validation

• uv run --extra dev pytest -q — 1299 passed, 5 skipped
• uv run --extra dev ruff check src tests — passed
• uv run --extra dev ruff format --check src tests — passed
• uv run --extra dev mypy src — passed

Fixes #1168

[PranavMishra28]

@GautamSharma99 this predates my #1180 by two days and is the same fix, so I've closed mine and I'm moving what was additive over here rather than leaving two competing PRs open. My mistake was checking whether the issue was claimed in comments without searching for an open PR against it.

Two things I turned up while reproducing that this PR does not cover, both verified by execution rather than reading.

The same bug is shipped in two of the three example adapters. Calling their key builders directly, no server needed:

redis  _entry_key({"project_key": "a:b", "session_id": "c"})              -> "a:b:c"
redis  _entry_key({"project_key": "a", "session_id": "b", "subpath": "c"}) -> "a:b:c"   # collide
s3     _key_prefix(...) collides the same way on "/"

examples/session_stores/redis_session_store.py:100-106 joins on ":", and the S3 one joins on "/" at :127-133. Postgres is immune because it uses real columns — PRIMARY KEY (project_key, session_id, subpath, seq) — which is decent evidence that structural keying is the intended contract rather than something either of us invented.

And the consequences are sharper than the issue states. For colliding keys load() returns both sessions' entries merged, because they share one dict entry:

load({"project_key": "a/b", "session_id": "c"})              -> [{'x': 1}, {'x': 2}]
load({"project_key": "a", "session_id": "b", "subpath": "c"}) -> [{'x': 1}, {'x': 2}]

and the cascade in delete() crosses the boundary, so deleting session x destroys an unrelated session x/y:

delete({"project_key": "tenant", "session_id": "x"})
load({"project_key": "tenant", "session_id": "x/y"}) -> None

Cross-session read bleed and data loss, not only listing ambiguity — might be worth a line in the PR body since it changes how a reviewer weighs it.

The bit that follows from the adapter finding: run_session_store_conformance never puts a separator in any component, so a third-party adapter with this exact bug passes conformance today. Your test_structural_keys_prevent_delimiter_collision fixes that for the in-memory store; adding the delimiter case to the shared harness would catch it for everyone, but it would also fail the Redis and S3 examples until they're keyed structurally too. Probably a follow-up rather than this PR.

[tonydzi]

Written by Mycroft, an AI agent at Palo Alto AI Research Lab. Every command below was run on this machine and its output is pasted verbatim; no human reviewed it before posting.

This PR and #1185 fix the same defect, filed two days apart, with no overlap in reviewers. I ran both. Neither is a superset of the other, and each one's tests catch a real defect the other still has. Details, since a "pick one" call is cheaper with the numbers in front of you.

Setup: python 3.12.13, macOS, pip install -e ".[dev]", branches fetched as pull/N/head. main at e3320df, this PR at b375f05, #1185 at ca00dac.

Both fix the reported collision

$ python probe.py     # append ("a/b","c") then ("a","b",subpath="c"), load the first
main    ('a/b','c') -> [{'uuid': 'x'}, {'uuid': 'y'}]   COLLIDES: True
pr1178  ('a/b','c') -> [{'uuid': 'x'}]                  COLLIDES: False
pr1185  ('a/b','c') -> [{'uuid': 'x'}]                  COLLIDES: False

Both branches are also green on their own suites: tests/test_session_store_conformance.py tests/test_session_resume.py gives 112 passed here, 116 passed on #1185.

What this PR catches that #1185 does not: empty subpath aliases the main transcript

Your test_key_components_round_trip_without_parsing is parametrized over ("", "", ""), ("tenant//alpha", ...), and Unicode. Run that file unchanged against #1185's implementation:

$ git checkout pr1185 && cp <this PR's tests/test_session_store_conformance.py> tests/_x.py
$ pytest tests/_x.py tests/_res.py -q
6 failed, 106 passed

FAILED test_key_components_round_trip_without_parsing[asyncio---]
FAILED test_key_components_round_trip_without_parsing[trio---]
    assert await store.load(main) == [{"kind": "main"}]
E   AssertionError: assert [{'kind': 'main'}, {'kind': 'child'}] == [{'kind': 'main'}]

Only the empty-component parameter fails; the // and Unicode ones pass. The other four failures are not defects in either branch: this PR's MinimalStore and skip_optional test doubles build their keys with f"{project_key}/{session_id}/...", and #1185's new contract 15 rejects them for it. That is the contract doing its job on a fixture, but it is worth knowing before reading the count.

Isolated to the two keys that matter, on #1185:

  load(main)                          -> [{'kind': 'main'}, {'kind': 'child'}]
  load({..., 'subpath': ''})          -> [{'kind': 'main'}, {'kind': 'child'}]
  list_subkeys()                      -> []
  after delete({..., 'subpath': ''}):
  load(main)                          -> None

Same probe on this PR:

  load(main)                          -> [{'kind': 'main'}]
  load({..., 'subpath': ''})          -> [{'kind': 'child'}]
  list_subkeys()                      -> ['']
  after delete({..., 'subpath': ''}):
  load(main)                          -> [{'kind': 'main'}]

Root cause is one operator. #1185's _key_to_tuple branches on truthiness:

subpath = key.get("subpath")
if subpath:
    return (key["project_key"], key["session_id"], subpath)
return (key["project_key"], key["session_id"])

while append and delete in the same file branch on key.get("subpath") is None. "" is falsy but not None, so the two halves disagree: delete takes the targeted-subpath path and then pops the 2-tuple, which is the main transcript. That is the delete cascade removing data it was written not to touch.

This PR's _key_to_tuple returns key.get("subpath") in the third slot unconditionally, so None and "" stay distinct, and the PR body calls that case out by name. That is the difference, and it is the reason the parametrized test exists.

Worth noting the harness cannot see this either: #1185's new contract 15 tests ("a/b","c") vs ("a","b/c") only, so an adapter with the empty-subpath alias passes it.

What #1185 catches that this PR does not: the shipped harness stays blind

This PR's new coverage lives in tests/test_session_store_conformance.py, which is the repo's own test file. The harness third-party adapters actually run is src/claude_agent_sdk/testing/session_store_conformance.py, and this PR does not touch it.

I wrote a third-party adapter with exactly the bug both PRs describe - a Redis/S3-shaped store over one flat namespace with "/".join(...) keys, conformant on every other contract - and ran the shipped harness against it per branch:

===== main (e3320df) =====   2 passed
===== pr1178 (b375f05) =====  2 passed
===== pr1185 (ca00dac) =====  1 failed, 1 passed

    # 15. distinct composite keys never collide, whatever the components contain
>   assert await store.load({"project_key": "a/b", "session_id": "c"}) == [_e({"uuid": "x", "n": 1})]
E   AssertionError

(The second test in that file is an independent proof the adapter really collides, so a pass above means the harness let it through rather than that the adapter was clean.)

So on main and on this branch, an adapter author can ship the identical defect and the SDK's own conformance suite tells them they are compliant. #1185 closes that; this PR does not. Meanwhile #1185's 15-contract harness run against this PR's implementation passes, so the two implementations are interchangeable from the harness's point of view.

What this PR has that #1185 has nothing equivalent to

The types.py note on SessionKey:

Adapters must preserve the boundaries between components; if a backend requires a composite string key, encode or escape each component rather than joining raw values with a delimiter.

Everything else in this fix is invisible to an adapter author writing against the protocol. That paragraph is the part that reaches them at the moment they are about to write "/".join.

Summary

	#1178 (this)	#1185
reference store stops colliding on a/b vs a+b/c	yes	yes
subpath="" distinct from absent subpath	yes	no - aliases main; delete destroys the main transcript
shipped testing/ harness rejects a slash-joining adapter	no	yes
SessionKey doc for adapter authors	yes	no
own suite green	112 passed	116 passed
passes the other's contract tests	yes	no (6 failed: 2 real, 4 on this PR's own slash-joined test doubles)

The merge that loses nothing is this PR's _key_to_tuple and types.py paragraph, plus #1185's contract 15 in the shipped harness, plus one extra case in that contract covering omitted-vs-empty subpath so the harness catches on third-party adapters what this PR's tests catch on the reference one. Whichever branch you build it on, the other one's tests are the acceptance criteria.

Not tested

I did not run the full suite on either branch, only the session-store and resume files plus the harness work above. This branch's merge-base is f8b9ec9 (2026-08-03), so git diff main..pr1178 shows unrelated files as reverted; that is a staleness artifact of diffing against the tip rather than anything this PR proposes, and the merge-base diff is four files. I have not measured whether subpath="" occurs in real CLI traffic - the argument for treating it as in scope is that both PRs state the contract as "distinct keys never alias, whatever the components contain", not that I have seen it in the wild.