[magicYang1573]

Description

Expose standalone soft-pin controls for existing Mooncake Store objects, so a serving controller can retain or release KV after a request completes without rewriting the objects or attaching retention settings to another write.

The implementation reuses the existing write-time soft-pin deadline, accounting, and expiration machinery. The master admin HTTP service exposes:

• POST /api/v1/soft_pin: {"tenant_id":"default","keys":["object-key"],"ttl_ms":60000}
• POST /api/v1/soft_unpin: {"tenant_id":"default","keys":["object-key"]}

Both return per-key results, e.g. {"results":[{"key":"object-key","error_code":0}]}. The admin service uses its existing port (default 9003).

Pin sets the deadline to the master's current time plus the requested TTL; renewal and shortening both work. Unpin clears soft protection immediately, without counting session references. Payloads, read leases, hard pins, and session tags retain their existing behavior. Retention policy and coordination between sessions belong to the caller. Existing pressure-eviction settings still apply.

The default maximum soft-pin TTL is now 7 days (604800000 ms), with CLI/configuration examples and documentation aligned. Requests are bounded to 4096 keys and preserve per-key missing/unfinished-object errors. Malformed JSON, including trailing garbage or concatenated values, is rejected before any pin state changes.

Related work

• Companion Dynamo integration: ai-dynamo/dynamo#17092, with custom-policy helpers for block hashes, whole sessions, and session frontiers.
• Dynamo session residency prerequisite: feat(router): attribute Mooncake session residency from SGLang's direct linker ai-dynamo/dynamo#16610.
• Related SGLang linker session tagging: [Feat] mem_cache: tag Mooncake linker offloads with the writing session sgl-project/sglang#44611; Mooncake event attribution: [Store] Add session IDs to KV events for Dynamo session prefix indexer #4683.

Suggested Merge Priority

• P2 — Normal: new feature for a confirmed use case

Module

• Mooncake Store (mooncake-store)
• Docs

Type of Change

• New feature
• Documentation update

How Has This Been Tested?

Test commands:

# BUILD_DIR is the configured local TCP build.
"$BUILD_DIR/mooncake-store/tests/master_admin_server_test"
pre-commit run --files $(git diff --name-only --diff-filter=ACMR upstream/main...HEAD)

Test results:

• Unit tests pass: 65 admin HTTP tests, including invalid trailing JSON leaving real pin counts unchanged.
• Integration tests pass.
• Manual end-to-end testing done.

Full inference E2E passed on the committed Mooncake c8efd8d16e1d6522950aec754ec42710178415e8 and Dynamo 204759d1965c8b000fb1358994a1b2201066a1e4 builds, with open-source SGLang 779adb4b82243e7743be60a305dc62ca3bee3a3a, Qwen3-0.6B, one GPU / TP1, HiCache write-through, and Mooncake TCP:

HTTP test frontend using Dynamo KvRouter SDK
  -> real SGLang inference -> HiCache -> Mooncake Store
  -> real worker/Store KV events -> Dynamo SPI
  -> custom policy -> Mooncake admin pin/unpin

A 512-token prompt generated 8 tokens and produced 8 indexed blocks / 16 MHA K/V objects. All 9 E2E checks passed: real event-to-key resolution; hash/session/frontier helper paths and invalid selections; malformed JSON without mutation; seven-day TTL boundary; one unpin despite two session references; partial failures, renewal, shortening and expiration; unchanged KV payloads; preserved read leases; and removal events invalidating key resolution. No synthetic events or manual SPI insertion were used.

This run exercised upstream SGLang's HiCache path, not the direct-linker branch in #44611. The local E2E harness is not included in this PR. TP>1, RDMA, memory-pressure eviction, HA, load testing, and the stock OpenAI frontend were not covered.

Checklist

• I have performed a self-review of my own code
• I have formatted my code using ./scripts/code_format.sh
• I have run pre-commit on the files changed in this PR and all hooks pass
• I have updated the documentation
• I have added tests to prove my changes are effective
• For changes >500 LOC: I have filed an RFC issue — not applicable (385 added lines)

Formatting was checked through the changed-file pre-commit hooks.

AI Assistance Disclosure

• AI tools were used: OpenAI Codex assisted with implementation, regression tests, local E2E validation, and this PR description.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

An organization owner can choose the repository organization as the billing source for reviews requested by members with a paid Copilot license. Learn about Copilot code review billing.

[stmatengss]

These three whitespace-only suggestions fix the Check code format failure. Applying all three to c8efd8d16e1d6522950aec754ec42710178415e8 locally passed ./scripts/code_format.sh --check --changed-lines --base origin/main with clang-format 20.1.8 and all applicable pre-commit hooks across the 17 PR files. The suggestions can be applied together in one batch. Prepared with OpenAI Codex.