docs(spec): record DeleteDataRequestSchema's consumer and why the DELETE data door carries no requestSchema (#16191)

The docblock above `DeleteDataRequestSchema` in `packages/spec/src/api/protocol.zod.ts` was bare. It now records three verified facts for the next reader who greps the name and sees "exported, documented, zero safeParse call sites": the schema is the request contract of `DataProtocol.deleteData()` (consumed statically via the `DeleteDataRequest` alias); it deliberately carries no REST-door `requestSchema` under #3899, which the catalog entry states in place of the key and `plugin-rest-api.schema-refs.test.ts` pins ("requestSchema appears only on body-carrying methods"); and drift between the schema and that door is caught at compile time by the typed request literal `ServerScopedDataRequest` in `packages/rest/src/rest-server.ts` (#15866), not by a runtime parse.

Comment and changeset only — no shape, `.describe()`, or export change; no other `*RequestSchema` docblock is touched.


Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno

Co-authored-by: Claude <noreply@anthropic.com>

Author: huangyiirene

.changeset/delete-data-request-schema-provenance.md

@@ -0,0 +1,9 @@
+---
+"@objectstack/spec": patch
+---
+
+Record, on `DeleteDataRequestSchema` itself, what it is for and why the DELETE data door carries no `requestSchema` for it.
+
+The schema is the request contract of `DataProtocol.deleteData()`, consumed statically through the `DeleteDataRequest` type alias and parsed at runtime nowhere — a grep that finds "exported, documented, zero `safeParse` call sites" is reading the wrong surface, and had already filed it once as a gap. Its docblock now says so; records that the absence of a `requestSchema` on `DELETE /api/v1/data/:object/:id` is a pinned decision (#3899 — the catalog entry states it in place of the key, and `plugin-rest-api.schema-refs.test.ts` goes red if one is added, because the route reads no body); and points at the compile-time check (#15866) under which a field added to the schema as required reddens the door at build instead of being silently unsent.
+
+Documentation only: no shape, `.describe()` text, or export changes. `@objectstack/spec` ships the new text in its published type declarations and in the source file it publishes directly via its `src/**/*.zod.ts` entry.

packages/spec/src/api/protocol.zod.ts

@@ -2125,6 +2125,30 @@ export const UpdateDataResponseSchema = lazySchema(() => z.object({
 
 /**
  * Delete Data Request
+ *
+ * [#13852] The request contract of {@link DataProtocol.deleteData} — its
+ * declared parameter type is the `DeleteDataRequest` alias below. That
+ * protocol boundary is this schema's whole job: it is consumed statically, by
+ * the compiler, and parsed at runtime nowhere in the tree. A grep that finds
+ * "exported, documented, zero `safeParse` call sites" is reading the wrong
+ * surface — #13852 is that grep, filed once already.
+ *
+ * It deliberately carries no REST-door `requestSchema` (#3899):
+ * `DELETE /api/v1/data/:object/:id` reads no body — `object` and `id` are
+ * path-bound, `expectedVersion` rides `?expectedVersion` / `If-Match` — so a
+ * schema on that door would promise a validation nothing can violate. The
+ * catalog entry in `plugin-rest-api.zod.ts` says so in place of the key, and
+ * the pin in `plugin-rest-api.schema-refs.test.ts` ("requestSchema appears
+ * only on body-carrying methods") goes red if one is added. ⛔ Do not wire
+ * one, and do not retire this schema either — it types a shipped interface
+ * method.
+ *
+ * Drift between this schema and that door is caught at COMPILE time, not by a
+ * runtime parse: the door's request literal is typed against
+ * `DeleteDataRequest` (`ServerScopedDataRequest` in
+ * `packages/rest/src/rest-server.ts`, #15866 / PR #16071), so a field added
+ * here as REQUIRED reddens that file at build, naming the route that would
+ * otherwise have gone on not sending it.
  */
 export const DeleteDataRequestSchema = lazySchema(() => z.object({
   object: z.string().describe('Object name'),