Skip to content

0011: Shared store, idempotent writes and dependencies

Status: proposed for M2 (step 1 of proposal 0010). Covers spec EXE-4, the shared half of SEC-6, and the section 9.2 rule that correctness must not depend on process-local state.

Problem

A write that times out is reported as ambiguous_write, and the agent cannot tell whether repeating it will do it twice. Single-use state tokens were single-use per process only. Handlers reached upstream clients through globals.

Proposal

Store

OunceServer(store=...) takes an OunceStore: get, put, put_if_absent and delete on JSON objects, namespaced and with an expiry, plus shared (whether put_if_absent is atomic across processes).

Store Shared claims Use
MemoryStore (default) No Development, single replica
RedisStore(redis.asyncio client) Yes (SET NX PX) Multiple replicas
KeyValueStore(any py-key-value-aio store) No: data is shared, claims are atomic per process Disk, Postgres, DynamoDB and others, one writer

Keys are digests, so no caller data appears in key names. py-key-value-aio is already a FastMCP 4 dependency; Redis needs the redis package, which OunceMCP does not install.

Idempotent writes (EXE-4)

@server.tool(effect=Effect.WRITE, idempotency=True) or idempotency=Idempotency(ttl_s=86400, grace_s=60, wait_s=5). Reads cannot opt in. The key is the principal, the tenant, the tool and a digest of the normalized arguments, or a client key from _meta (ouncemcp/idempotency_key or idempotencyKey) bound to the same caller and tool.

Record A duplicate call gets
running Waits up to wait_s for the result, else a retryable write_in_progress (transient)
done The stored result, with _meta.ouncemcp.replayed = true
unknown write_status_unknown (ambiguous_write): check the state or use a new key
a client key with different arguments idempotency_key_reused (validation)

A failure that cannot have changed anything (validation, authentication, permission, not found, rate limit, or a request never sent) clears the record. Any other failure marks it unknown.

Deadlines. The call deadline bounds the caller's wait, not the write. A write past its deadline keeps running for up to grace_s; the caller gets write_still_running (ambiguous_write) with "call again with the same arguments: you get its result once it finishes, and it will not run twice". The finished result is stored, so the retry replays it. This is the ticketing pilot's key test, and it is tested here.

Shared single use (SEC-6)

await ctx.consume_state(token, kind, request=...) verifies a state token and records its use in the store, so a second use fails on any replica sharing the store.

Dependencies

OunceServer(deps=...) takes any object; handlers read ctx.deps. ouncemcp.security.guarded_client(...) returns an httpx2.AsyncClient with the passthrough guard installed, for upstream calls.

Alternatives considered

  • Idempotency on by default for writes. It would silently turn two intended identical writes (two identical reminders) into one. Opt-in per tool, with the ticketing pilot and docs using it, keeps behavior explicit.
  • Cancel the write at the deadline, as before. Cancellation is not rollback: the upstream may already have applied it, and the result would be lost. Letting it finish within a grace period and storing the result is what makes the retry safe.
  • Atomic claims through the generic key-value protocol. It has no compare-and-set, so claims would race across replicas. Redis gets a dedicated adapter instead.

Impact on tokens and task success

Definitions do not change. Replayed results carry one extra _meta field. Agents that retry after a timeout get the result instead of a duplicate.

Migration notes

None for existing tools. Fixed while building this: passing an empty PartitionedCache as cache= used to be replaced by a new one (an empty cache is falsy); the server now keeps the object passed.