Strawman: Resource operations (stat, create, update, delete) with version-based concurrency

README.md

@@ -15,6 +15,7 @@ This repository holds the working documents and reference implementations for **
 | [Problem Statements](docs/problem-statements.md) | What is missing from Resources today, as six problem statements with a running example |
 | [Use Cases](docs/use-cases.md) | Concrete situations Resource operations should serve |
 | [Open Questions](docs/open-questions.md) | Questions the group needs to settle, starting with the charter's |
+| [Resource operations strawman](docs/proposals/resource-operations.md) | Draft `stat`, `create`, `update`, `delete` with revision-based concurrency, for discussion |
 | [Decision Log](docs/decisions.md) | ADR-lite record of the group's decisions, and the vehicle for proposing changes |
 | [Related Work](docs/related-work.md) | SEPs, extensions, and discussions this work builds on |
 | [Implementations](docs/implementations.md) | Servers, SDKs, and hosts that implement Resource operations |
@@ -27,7 +28,7 @@ Nothing under `docs/` is part of a specification. A specification will live unde
 
 | Language | Directory | Package | Status |
 | :--- | :--- | :--- | :--- |
-| Python | `python/sdk/` | `mcp-ext-filesystems` | Planned |
+| Python | `python/sdk/` | `mcp-ext-filesystems` | Prototype |
 
 The charter's success criteria call for reference implementations in at least two Tier 1 SDKs.
 

conformance/README.md

@@ -2,4 +2,8 @@
 
 Conformance scenarios for each new Resource operation method and schema element, as the charter requires. Scenarios should run against any implementation, not only the ones in this repository, so that independent servers exercising the write path can be checked against a common client.
 
-No scenarios yet. They arrive alongside the first proposal that defines a method.
+| Scenarios | Covers |
+| :--- | :--- |
+| [resource-operations-conflicts.md](resource-operations-conflicts.md) | Create-if-absent and stale `ifMatch` from the [Resource operations strawman](../docs/proposals/resource-operations.md) |
+
+Scenarios are written as request and expectation tables for now. A runnable harness can come once the methods settle.

conformance/resource-operations-conflicts.md

@@ -0,0 +1,36 @@
+# Scenarios: write conflicts
+
+Implementation-independent checks for the conflict behaviour in the [Resource operations strawman](../docs/proposals/resource-operations.md). A harness runs them against any server that declares `io.modelcontextprotocol/resource-operations`, using one or two client connections.
+
+Conventions:
+
+- `<U>` is a URI the server accepts for writes and that does not exist at the start. The harness gets it from configuration.
+- `<R…>` are revisions captured from earlier responses. Revisions are opaque: compare them only for equality, never parse them.
+- "Precondition failed" means the error code assigned to precondition failures (provisionally `-32010`).
+- Each step lists the request and the checks on its response. A step fails the scenario if any check fails.
+
+## RO-CONFLICT-1: create-if-absent
+
+| # | Connection | Request | Expect |
+| :--- | :--- | :--- | :--- |
+| 1 | A | `resources/create {uri: <U>, contents: {text: "a"}}` | Result. `revision` is a non-empty string; save as `<R1>`. `changes` contains `{uri: <U>, effect: "created", revision: <R1>}`. |
+| 2 | B | `resources/create {uri: <U>, contents: {text: "b"}}` | Error. Code is precondition failed. `data.uri` = `<U>`, `data.reason` = `"alreadyExists"`, `data.currentRevision` = `<R1>`. |
+| 3 | A | `resources/stat {uri: <U>}` | Result. `revision` = `<R1>`. The second create changed nothing. |
+
+## RO-CONFLICT-2: lost update
+
+The memory-server case from [use cases](../docs/use-cases.md): two sessions read the same revision and both write it back.
+
+| # | Connection | Request | Expect |
+| :--- | :--- | :--- | :--- |
+| 1 | A | `resources/create {uri: <U>, contents: {text: "0"}}` | Result. |
+| 2 | A | `resources/stat {uri: <U>}` | Result. Save `revision` as `<R1>`. |
+| 3 | B | `resources/stat {uri: <U>}` | Result. `revision` = `<R1>`. |
+| 4 | A | `resources/update {uri: <U>, contents: {text: "0A"}, ifMatch: <R1>}` | Result. Save `revision` as `<R2>`; `<R2>` != `<R1>`. `changes` contains `{uri: <U>, effect: "updated", previousRevision: <R1>, revision: <R2>}`. |
+| 5 | B | `resources/update {uri: <U>, contents: {text: "0B"}, ifMatch: <R1>}` | Error. Code is precondition failed. `data.reason` = `"revisionMismatch"`, `data.currentRevision` = `<R2>`. |
+| 6 | B | `resources/stat {uri: <U>}` | Result. `revision` = `<R2>`. The rejected write changed nothing. |
+| 7 | B | `resources/update {uri: <U>, contents: {text: "0AB"}, ifMatch: <R2>}` | Result. `changes` contains `previousRevision: <R2>`. |
+| 8 | B | `resources/delete {uri: <U>, ifMatch: <R1>}` | Error. Code is precondition failed. `data.reason` = `"revisionMismatch"`. |
+| 9 | A | `resources/stat {uri: <U>}` | Result. The resource still exists. |
+
+Optional, if the server reads back what it stores: after step 7, `resources/read {uri: <U>}` returns text `"0AB"`.

docs/decisions.md

@@ -4,7 +4,7 @@ This document records significant decisions made by the Filesystems Working Grou
 
 For background on the ADR format, see [adr.github.io](https://adr.github.io/).
 
-No decisions have been recorded yet. The first one the charter calls for is listed in [open-questions.md](open-questions.md).
+No decisions have been accepted yet. The first one the charter calls for is listed in [open-questions.md](open-questions.md).
 
 ## Entry format
 
@@ -26,3 +26,20 @@ Add new entries below this section, oldest first. A pull request that adds an en
 ```
 
 ---
+
+### 2026-10-09: Strawman for Resource operations: stat, create, update, delete with revision-based concurrency
+
+**Status:** Proposed
+
+**Context:** The [charter](https://modelcontextprotocol.io/community/working-groups/filesystems) asks for create, update, delete, and `stat`, typed errors, and optimistic concurrency control on writes including create-if-absent (PS4.1, PS4.3, PS4.5, PS5.1 to PS5.3, PS6.1, and PS6.2 in the [problem statements](problem-statements.md), where PS*n*.*m* is item *m* of Problem Statement *n*; cross-cutting [open questions](open-questions.md) 1 and 3). Options considered for concurrency: no precondition (last writer wins), timestamps (`lastModified`), an opaque server-minted revision compared on write, and that revision optional on update or delete. For listing: a new method, or the `resources/directory/read` method already defined by the Skills extension (SEP-2640).
+
+**Decision:** Use [docs/proposals/resource-operations.md](proposals/resource-operations.md) as the group's starting strawman: an extension `io.modelcontextprotocol/resource-operations` (provisional) with `resources/stat`, `resources/create` (create-if-absent only), `resources/update` and `resources/delete` (both require `ifMatch`); an opaque `revision` as the concurrency token, the term [Problem Statement 5](problem-statements.md#problem-statement-5-optimistic-concurrency-control) uses; a precondition-failed error carrying `currentRevision`; and reuse of `resources/directory/read` unchanged for listing. Search, glob, bulk reads, and ranges are deferred.
+
+**Rationale:** An opaque revision identifier is what HTTP ETags, S3, and GCS already use, survives coarse clocks, and lets each server choose a counter, digest, or backend generation. Required `ifMatch` on update and delete rules out lost updates by omission. Reusing SEP-2640's method avoids two listing methods for the same tree. The change-set vocabulary (entries with `effect`) follows Kryspin Ziemski's working document shared in #filesystem-wg, so later Query and Range work can build on it; that document calls the token `version`, and this draft uses `revision` to match the problem statements. A Python prototype built on the SDK's `Extension`/`MethodBinding` API and conformance scenarios accompany the draft.
+
+**References:**
+- [Proposal](proposals/resource-operations.md), [Python prototype](../python/sdk/), [conformance scenarios](../conformance/)
+- [SEP-2571](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2571) (closed): `resources/create` and `resources/delete`
+- [SEP-2640](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2640): Skills extension, `resources/directory/read`
+- [SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133), [SEP-3371](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/3371): extensions framework and SDK extension points
+- Kryspin Ziemski's working document "MCP Resources as Addressable Domain State", shared in #filesystem-wg

docs/implementations.md

@@ -10,7 +10,7 @@ To add or update a row, open a pull request. Keep notes to one line.
 
 | Implementation | Language | Status | Notes |
 | :--- | :--- | :--- | :--- |
-| [`python/sdk/`](../python/sdk/) | Python | `planned` | Reference implementation in this repository |
+| [`python/sdk/`](../python/sdk/) | Python | `prototype` | Reference implementation of the [strawman](proposals/resource-operations.md) in this repository |
 
 ## Servers