fix(agentserver): preserve local state-store ordering and paging

[JiahuiGu (Jiahui-Gu)]

Summary

Fix the local FoundryStateStore ordering/pagination contract as a standalone SDK change. No LangChain-specific keys, sample branches, generated models, service requests, or public API signatures change.

Root cause and scope

The local backend persists public timestamps in whole seconds and previously sorted equal timestamps by a SHA256-derived item ID. Rapid writes therefore had arbitrary creation order. The problem reproduces without an agent: after saving twelve checkpoints, a descending one-item query selected step 3 rather than step 11. Upgrading LangChain did not introduce the defect.

The same listing path also filtered away cursor items before resolving their position and returned the beginning of the entire prefix for before, rather than the adjacent preceding page. This change fixes that listing lifecycle rather than special-casing one checkpoint consumer.

Design

• Persist a private per-store creation sequence in the existing atomically replaced JSON document. Creation assigns a sequence; updates preserve position, ID, creation time, ETag preconditions, and write-sliding TTL. Expiry/deletion does not reuse the sequence counter.
• Give recreated items fresh opaque IDs so an old cursor cannot silently refer to a replacement. Existing persisted IDs remain unchanged, as do IDs on ordinary updates.
• Continue exposing integer timestamps. Private sequence/expiry fields never appear in public item models, item references, or key pages.
• Initialize legacy documents using their previous deterministic (created_at, id) order. Original same-second creation order cannot be recovered from those files; it is not guessed. A file rewritten by an older SDK without sequence fields follows the same compatibility path.
• Resolve cursor positions before tag filtering, page backward from the nearest preceding matches, preserve requested order and envelope fields, and enforce the documented local limit/order bounds.

The generic store does not learn application revision ordering. LangGraph's checkpoint-ID ordering belongs in its adapter and is addressed separately by langchain-azure #1209. There is no latest-checkpoint pointer or sample fallback in this PR; neither fix depends on the other's release.

Validation

Tests were added and run red before implementation: same-second order, both creation APIs, backward paging, filtered-out cursor positions, expiry, and legacy-file continuation failed on the original backend. Invalid-query and recreated-cursor regressions were also observed failing before their fixes.

Check	Result
Core package, Python 3.11, source checkout	1198 passed, 64 skipped
Focused storage/local-provider/path regression	154 passed before the last additional mixed-writer test; the complete Core run above includes it
Storage suites, minimum Python 3.10	73 passed
Responses package regression with both current source packages	2297 passed, 83 skipped
New local ordering suite	20 passed, including real subprocess reopen
Original frozen-clock twelve-checkpoint reproduction	latest and exact both return step 11
Black with repository config, changed-source mypy, pylint with Azure checker	Pass

Core skips are existing POSIX-only/Windows-encoding checks and live telemetry tests without Azure configuration. Responses skips are existing platform/fixture-dependent tests. These are local tests; no cloud-service correctness, model-quality evaluation, simultaneous multi-process writers, or full CI matrix is claimed. Local state access retains its existing process-local locking and atomic-file replacement boundary.

Compatibility / release notes

• Public resource timestamps, signatures, keys, and retained IDs are unchanged. IDs remain opaque; delete/recreate now represents a new item incarnation.
• Old same-second history retains its previous order; this cannot retroactively repair chronology that the old file never recorded.
• A Chronus fix entry and the state-store guide describe the behavior and limitations. No release or package-version bump is performed here.

AI assistance: Codex assisted with implementation and verification.

[github-actions]

Thank you for your contribution JiahuiGu (@Jiahui-Gu)! We will review the pull request and get back to you soon.

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
7 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.