S2 0.3.0: a single-document answer may describe a workspace in part

docs/specs/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Changes to the specifications in this directory. Each specification is versioned independently.
 
+## 2026-09-26 — S2 0.3.0: a partial single-document answer
+
+In single-document mode a document may carry `data` together with `error` diagnostics. It describes
+everything except what those diagnostics name; the producer names each part it could not describe
+(a workspace member or a package) in the diagnostic's new optional `path` field, and a consumer uses
+the rest of the document (S2-3.4-12, S2-3.4-13). `data` is present when the command described the
+workspace in whole or in part; a command without `data` has still failed (S2-3.4-11). A consumer
+written for 0.2.0 reads such a document as a success with errors, which is the intended reading.
+mcpp implements it with mcpp-community/mcpp#699 (in #702); before, one workspace member's planning
+failure used to remove every member's sets.
+
 ## 2026-09-25 — S3: issue categories, the degraded hold, module syntax in semantic tokens
 
 Added `category` (optional) to `CxxModulesIssue`: `code`, `engine`, `environment` or `project`,

docs/specs/README.md

@@ -5,7 +5,7 @@ This directory holds the normative specifications that let C++ named modules be
 | Spec | Title | Version | Status | Schema |
 |---|---|---|---|---|
 | [S1](s1-build-database.md) | C++ Build Database: IDE Profile | profile-version 0.2.0 | Draft | [s1-build-database.schema.json](schema/s1-build-database.schema.json) |
-| [S2](s2-discovery.md) | Build Database Discovery Protocol | 0.2.0 | Draft | [s2-discovery.schema.json](schema/s2-discovery.schema.json) |
+| [S2](s2-discovery.md) | Build Database Discovery Protocol | 0.3.0 | Draft | [s2-discovery.schema.json](schema/s2-discovery.schema.json) |
 | [S3](s3-lsp-extensions.md) | Language Server Protocol Extensions for C++ Modules | protocol version 1 | Draft | TypeScript interfaces in the text |
 | [S4](s4-semantic-kit.md) | Semantic Kit | kit-version 1 | Draft | [s4-kit.schema.json](schema/s4-kit.schema.json) |
 | [S5](s5-semantic-query.md) | Semantic Queries for C++ Code | 0.1.0 | Draft | TypeScript interfaces in the text |

docs/specs/s2-discovery.md

@@ -3,7 +3,7 @@
 | | |
 |---|---|
 | Specification | S2 |
-| Version | 0.2.0 |
+| Version | 0.3.0 |
 | Status | Draft |
 | Schema | [`schema/s2-discovery.schema.json`](schema/s2-discovery.schema.json) |
 | Examples | [`examples/s2-request.json`](examples/s2-request.json), [`examples/s2-messages.jsonl`](examples/s2-messages.jsonl), [`examples/s2-envelope.json`](examples/s2-envelope.json) |
@@ -92,11 +92,13 @@ A producer that already prints machine-readable envelopes offers discovery as on
 | `kind` | string | MUST | A name ending in `.build-database`, for example `mcpp.build-database`. <a id="S2-3.4-2"></a><sup>S2-3.4-2</sup> |
 | `kindVersion` | integer | MUST | `1`. <a id="S2-3.4-3"></a><sup>S2-3.4-3</sup> |
 | `effects` | string[] | MUST | What running the command did, for example `read-project`. <a id="S2-3.4-4"></a><sup>S2-3.4-4</sup> |
-| `data` | object | conditional MUST | Present when the command succeeded: `database` (object, MUST), the S1 document; `watch` (string[], MUST), as in section 3.3; `inputs-fingerprint` (string, SHOULD), a digest of the inputs `watch` names. <a id="S2-3.4-5"></a><a id="S2-3.4-6"></a><a id="S2-3.4-7"></a><a id="S2-3.4-8"></a><sup>S2-3.4-5, S2-3.4-6, S2-3.4-7, S2-3.4-8</sup> |
-| `diagnostics` | object[] | MUST | Each with `code`, `severity` (`error`, `warning` or `note`) and `message`. <a id="S2-3.4-9"></a><sup>S2-3.4-9</sup> |
+| `data` | object | conditional MUST | Present when the command described the workspace in whole or in part: `database` (object, MUST), the S1 document; `watch` (string[], MUST), as in section 3.3; `inputs-fingerprint` (string, SHOULD), a digest of the inputs `watch` names. <a id="S2-3.4-5"></a><a id="S2-3.4-6"></a><a id="S2-3.4-7"></a><a id="S2-3.4-8"></a><sup>S2-3.4-5, S2-3.4-6, S2-3.4-7, S2-3.4-8</sup> |
+| `diagnostics` | object[] | MUST | Each with `code`, `severity` (`error`, `warning` or `note`) and `message`; `path` (string, MAY) names the file the diagnostic concerns, relative to the workspace root. <a id="S2-3.4-9"></a><sup>S2-3.4-9</sup> |
 
 The consumer writes nothing to the command's standard input. Before running it, the consumer reads the producer's protocol description, `<producer> --protocol-version`: a JSON object whose `kinds` maps kind names to versions and whose `commands` maps command names to the `effects` they may have. A consumer **MUST** use single-document mode only when `kinds` contains the build-database kind, and **MUST** run the command only when the workspace is trusted and the listed effects are acceptable. A command without `data` has failed; its `diagnostics` say why. <a id="S2-3.4-10"></a><a id="S2-3.4-11"></a><sup>S2-3.4-10, S2-3.4-11</sup>
 
+A document may carry `data` together with `error` diagnostics. It describes everything except what those diagnostics name: the producer **MUST** name each part it could not describe, such as a workspace member or a package, in an `error` diagnostic whose `path` is that part's build description file, and a consumer **SHOULD** use the rest of the document and report the errors. The command's exit status is non-zero in this case. <a id="S2-3.4-12"></a><a id="S2-3.4-13"></a><sup>S2-3.4-12, S2-3.4-13</sup>
+
 In this mode the producer does not write a database file. The consumer keeps the document where it keeps its own state.
 
 Example: [`examples/s2-envelope.json`](examples/s2-envelope.json).

docs/specs/schema/s2-discovery.schema.json

@@ -202,6 +202,10 @@
               },
               "message": {
                 "type": "string"
+              },
+              "path": {
+                "type": "string",
+                "description": "The file the diagnostic concerns, relative to the workspace root (section 3.4)."
               }
             }
           }