feat(spec)!: retire the unserved Virtual ObjectQL request protocol (#27028)

.changeset/27028-data-engine-rpc-protocol-retired.md

@@ -0,0 +1,28 @@
+---
+'@objectstack/spec': minor
+'@objectstack/objectql': patch
+---
+
+feat(spec)!: retire the unserved Virtual ObjectQL request protocol from `data/data-engine.zod.ts`
+
+Clause-②: no (narrowing)
+Metadata-protocol: narrowed
+
+<!-- adr-0087: registered data-engine-rpc-protocol-retired -->
+
+**BREAKING** for TypeScript and JSON Schema consumers of one block that nothing ever served. `@objectstack/spec/data` published a serialized request protocol for a "Virtual Data Engine" in another process: `DataEngineRequestSchema` and its nine `method` arms, plus `DataEngineContractSchema`. No such engine existed and nothing parsed the protocol. A census found no importer or parser in this repo outside the defining module, and zero hits in hotcrm, objectui and docs.objectos.ai. As published it was also unsafe to implement: every arm admitted a caller-supplied `context` (`isSystem` included), and the `execute` arm carried a raw driver command. The whole block is retired (ADR-0049 enforce-or-remove, by the maintainer's ruling A).
+
+| FROM | TO |
+|:--|:--|
+| `DataEngineFindRequestSchema`, `DataEngineFindOneRequestSchema`, `DataEngineCountRequestSchema`, `DataEngineAggregateRequestSchema` | in process, `IDataEngine.find` / `findOne` / `count` / `aggregate` with `EngineQueryOptions` / `EngineCountOptions` / `EngineAggregateOptions`; over the wire, the REST data routes (`/data/:object`, `POST /data/:object/query`) |
+| `DataEngineInsertRequestSchema`, `DataEngineUpdateRequestSchema`, `DataEngineDeleteRequestSchema` | `IDataEngine.insert` / `update` / `delete` with `DataEngineInsertOptions` / `EngineUpdateOptions` / `EngineDeleteOptions`; over the wire, the REST data routes, and `POST {basePath}/batch` for a batch |
+| `DataEngineVectorFindRequestSchema`, `DataEngineExecuteRequestSchema` | `IDataEngine.vectorFind?` / `execute?`, in process only |
+| `DataEngineRequestSchema` and the types `DataEngineRequest`, `DataEngineRequestParsed`, `DataEngineExecuteRequest`, `DataEngineInsertRequest`, `DataEngineVectorFindRequest` | none: there is no serialized engine-call protocol; call `IDataEngine` in process, or a hook or action body's `ctx.api.object(name)` |
+| `DataEngineContractSchema` | the `IDataEngine` interface (`@objectstack/spec/contracts`) |
+
+The one-line fix: replace an import of any name above with the `IDataEngine` method or option type in the right-hand column. An import left behind is `TS2305` after upgrade.
+
+The retirement kit:
+
+- **`@objectstack/spec`**: the ten request schemas, `DataEngineContractSchema`, the five types and their private helpers (`RpcQueryOptionsSchema` and the `filter`-only fold) are deleted. The ten published defs `data/DataEngineRequest` and `data/DataEngine{Find,FindOne,Insert,Update,Delete,Count,Aggregate,Execute,VectorFind}Request` leave `json-schema/` and the reference docs, registered in `RETIRED_DEFS_BY_MAJOR[18]`, and the D3 entry `data-engine-rpc-protocol-retired` names the doors that exist. There is no `retiredKey()` tombstone and no conversion: no metadata source authors these shapes, and no parse remains for a prescription to reach. `IDataEngine`, every `*OptionsSchema`, `RPC_QUERY_ALIAS_SLOTS`, `foldQueryAliasSlots` and the query-transport schemas are unchanged. Runtime behaviour is unchanged.
+- **`@objectstack/objectql`**: a comment that named `RpcQueryOptionsSchema` now names `QueryWithTransportSchema`. No behaviour changes.

content/docs/kernel/contracts/data-engine.mdx

@@ -27,7 +27,6 @@ import type {
   EngineDeleteOptions,
   EngineAggregateOptions,
   EngineCountOptions,
-  DataEngineRequest,
 } from '@objectstack/spec/data';
 
 export interface IDataEngine {
@@ -48,9 +47,6 @@ export interface IDataEngine {
     where?: any; limit?: number; fields?: string[]; threshold?: number;
   }): Promise<any[]>;
 
-  // Batch Operations (optional, transactional)
-  batch?(requests: DataEngineRequest[], options?: { transaction?: boolean }): Promise<any[]>;
-
   // Raw Command Escape Hatch (optional)
   execute?(command: any, options?: Record<string, any>): Promise<any>;
 
@@ -470,8 +466,8 @@ declares one; none carries a `readonly` policy of its own any more — see
 <Callout type="warn">
 `WriteObservabilityOptions` is a **TS-contract-level, in-process-only** bag —
 all three members. It is deliberately not part of the serializable Zod options schemas:
-a function is unrepresentable in JSON Schema and cannot cross the RPC (Virtual
-Data Engine) boundary, so remote callers never receive these events; and putting
+a function is unrepresentable in JSON Schema and cannot be serialized, so remote
+callers (REST, the client SDK) never receive these events; and putting
 `strictReadonlyWrites` in the serializable bag would let any client toggle
 write-refusal on a security-adjacent path (#5126 ruling). A remote caller can set
 none of the three, and for the strips it gets NEITHER behaviour: its write is
@@ -569,17 +565,12 @@ const results = await engine.vectorFind?.('document', embeddingVector, {
 });
 ```
 
-### batch (Transactional)
-
-Execute multiple operations in a single transaction:
+### Several writes, atomically
 
-```typescript
-const results = await engine.batch?.([
-  { method: 'insert', object: 'project', data: { name: 'Website Redesign', status: 'active' } },
-  { method: 'insert', object: 'task', data: { title: 'Design mockups', status: 'open' } },
-  { method: 'insert', object: 'task', data: { title: 'Implement frontend', status: 'open' } },
-], { transaction: true });
-```
+There is no `batch` member: it was never implemented by any engine and was retired
+(ADR-0119 D3). In process, wrap the writes in `IObjectQLEngine.transaction(cb)`;
+for a batch over one object use the metadata protocol's `batchData` with
+`options.atomic: true`; over the wire, `POST {basePath}/batch`.
 
 ### execute (Raw Command)
 
@@ -624,7 +615,7 @@ detection locate drivers.
 <Callout type="warn">
 **Deprecated Parameter Names**
 
-The following legacy parameter names are accepted by the RPC layer for backward compatibility but should **not** be used in new code. The protocol normalizer resolves conflicts with canonical names taking precedence.
+The following legacy parameter names are accepted on the wire (the protocol normalizer) for backward compatibility but should **not** be used in new code. The protocol normalizer resolves conflicts with canonical names taking precedence.
 
 | Legacy (Deprecated) | Canonical | Notes |
 |:---------------------|:----------|:------|