Four client SDK routes answer a shape no published contract declares — `automation.create` / `automation.update` / `search` / `data.clone`

[os-zhuang]

Blocked-by: objectstack-ai/objectstack#8140

Filed out of #8140's implementation half, which bound 51 of its 55 erased return-type sites to
@objectstack/spec contracts. These four could not be bound, and the reason is the same in
each case: there is no type anywhere to bind to. They are a missing contract, not a missing
annotation, so they need a decision about what each endpoint promises rather than a sweep.

⛔ packages/spec was read-only on #8140 (domain:spec's single-owner surface), so nothing was
authored there. All four keep Promise< any > on main today, each with a docblock naming this
card's reasoning so the next sweep does not "finish" them by reaching for a near neighbour.

Measured at 1f6d04703.

The four

1–2. automation.create / automation.update — the route promises nothing

Both echo the request body, unvalidated as to shape:

• POST /automation ends deps.success(body) (packages/runtime/src/domains/automation.ts:982).
• PUT /automation/:name ends deps.success(definition) (same file, :1586) where
  definition = body.definition ?? body.

IAutomationService.registerFlow(name, definition: unknown): void
(packages/spec/src/contracts/automation-service.ts:389) returns nothing, so the service
contract has no return shape to relay. The body is checked for "is a non-array object" and handed
to the engine, whose refusal becomes a 400 (#8123) — but it is never parsed through FlowSchema,
so what comes back is the caller's own bytes. Declaring Flow here would be a claim about the
request that no validation backs.

The decision this needs: should these routes answer the registered, parsed flow
(FlowParsed — canonicalizeStoredFlow already produces exactly that), or keep echoing? The
first is a behaviour change with a real benefit (the caller learns what the engine actually
stored, defaults materialised); the second stays untypeable.

3. search — declared inline on the implementation, unreachable from the client

GET /api/v1/search relays protocol.searchAll(...) verbatim
(packages/rest/src/rest-server.ts:8259-8266). Its shape is declared as an inline return
annotation at packages/metadata-protocol/src/protocol.ts:9845-9863:

{ query: string;
  hits: Array< { object: string; id: string; title: string; snippet?: string; record: any } >;
  totalObjects: number; totalHits: number; truncated: boolean }

Not in @objectstack/spec, and @objectstack/metadata-protocol is not a dependency of
packages/client (its deps are @objectstack/core and @objectstack/spec only), so it is
unreachable even by import. Note hits[].record is itself any in the implementation's own
declaration — the erasure is not only at the SDK boundary here.

⚠️ Near-miss trap, verified at head. SearchResult
(packages/spec/src/contracts/search-service.ts:53) exists, is exported from
@objectstack/spec/contracts, and is the wrong type: it contracts the per-object
ISearchService.search, whose hits carry score / document, not this route's
object / title / snippet / record. Binding it would typecheck and ship a false
declaration. #8140 left a compile-time guard on that mismatch in
packages/client/src/return-type-precision.test.ts.

4. data.clone — a stable server-produced shape declared nowhere

POST /data/:object/:id/clone answers { object, id, sourceId, record }, produced at
packages/metadata-protocol/src/protocol.ts:9488-9493. Stable and server-produced, but declared
in no spec module. It is the structural sibling of the client's own CreateDataResult< T > plus
sourceId — which is what makes it tempting and why it is being written down instead: minting
that equivalence inside a consumer would create an undeclared second contract.

Why this is its own card rather than a rider

#3877's standing ruling (quoted in packages/rest/src/rest-route-ledger.ts:80-102) is that
authoring the missing route response schemas wholesale is not scheduled, because a response
schema is a product decision about what an endpoint promises and mass-producing them is how
declarations nobody validated come to exist — "⛔ DO NOT FILL A ROW THAT HAS NO CONFORMANCE
COVERAGE". #8140's 51 bound sites are outside that ruling (they relay contract types that already
exist and are already the declared return of the service method the route calls); these four are
squarely inside it. Each wants its own answer plus conformance coverage, which is a different
piece of work from a typing sweep.

Suggested shape

Four decisions, not one sweep. search and data.clone are the cheap pair — both have a stable
shape a schema can simply describe. automation.create / automation.update are the interesting
pair and should probably be answered together, since they are the same route class.

---

Generated by Claude Code

[claude]

Triage: → needs-user-decision + domain:spec — the four missing shapes are missing contracts (packages/spec), and the ruling the body cites (⛔ do not fill a row that has no conformance coverage) puts them squarely on the manual floor: each wants a product answer plus conformance coverage, not a typing sweep. Blocked-by: #8140 already in the body (typing sweep in flight). Type: Feature.

① 项目长远合理性:给这四个端点补契约声明是在缩小「路由回声、无承诺」的特例面;但 automation 两端点若声明 FlowParsed 会把「回声调用方字节」改成「回声已解析流程」,是一次真实的行为收敛 —— 方向与 contract-first 一致,代价是要动运行时回包。
② 实际业务拉动:今天写集成的客户从这四个端点拿到的要么是自己发出去的字节、要么是无声明的形状,SDK 侧全是 any —— 撞上的是「返回值没法安全消费」;search / data.clone 已有稳定形状,只是没人声明。
③ 防 AI 犯错:回声式响应是 AI 生成集成代码「看起来能跑」的温床 —— 声明并校验返回形状让错误在编译期响亮暴露;继续回声则错形静默流进客户数据。
④ 创业阶段不扩散:四个决定拆两对 —— search / data.clone 是便宜的一对(照实声明 + conformance 即可);automation 一对牵动运行时回包行为,零拉动时可先 defer,不必四个一起做。
推荐:A = 先裁 search / data.clone(照实声明 + conformance 覆盖),automation 一对单独再裁;B = 四个一起做;C = 全部 defer。回一个字母即可(「A,但 X」= 附加约束照录)。
置信缺口:本分析未实测 automation 回包在真实部署里是否已有消费方依赖「回声」形状 —— 若有,改回包即破坏性变更,需先做消费面盘点。

---

Generated by Claude Code