fix(spec): implement-objectos Rule #3 names the real request/response validation surface (#9614)

.changeset/implement-objectos-rule3-real-exports.md

@@ -0,0 +1,33 @@
+---
+"@objectstack/spec": patch
+---
+
+docs(spec): `implement-objectos.md` Rule #3 names real exports instead of `RequestEnvelope` / `ResponseEnvelope` (#9614)
+
+The published runtime-kernel prompt told an implementing agent to "validate
+`RequestEnvelope`" and "wrap in `ResponseEnvelope`". Neither has ever been an
+export of `@objectstack/spec` — measured across all 16 published
+`api-surface/*.json` entries — and `ResponseEnvelopeConfig*` is a config shape,
+not the envelope, so it was not a drop-in referent.
+
+Rule #3 now describes the validation surface the package actually has:
+
+- **Requests**: there is no single request envelope by design.
+ `StandardApiContracts` maps each standard operation to its `input`
+ (`CreateRequestSchema`, `UpdateRequestSchema`, `IdRequestSchema`,
+ `BulkRequestSchema`, and `QuerySchema` for `list`), and `ApiEndpointSchema`
+ carries the route's own shape — which is what makes `api/endpoint.zod.ts`, a
+ file the rule already cited, actually reachable from it.
+- **Responses**: `BaseResponseSchema` is the envelope skeleton that each
+ response type extends with its own `data`, and the rule now carries the
+ warning the schema's own docstring makes: `safeParse` alone does not prove
+ conformance, because the schema strips unknown keys and accepts a payloadless
+ `{ success: true }`. `envelopeViolations(body)` is the conformance check.
+
+The referents also move from prose into a fenced `import`, so
+`check:published-readme-exports` resolves them from now on — the blind spot that
+let the two fabricated names ship (prose symbols match neither an import clause
+nor a member call site) no longer covers this rule.
+
+No schema, no runtime behaviour and no authorable surface changes; the published
+prompt text does.

packages/spec/prompts/implement-objectos.md

@@ -38,8 +38,30 @@ in the qualified schemas (`TenantSecurityPolicySchema`, `PermissionSetSchema`).
 
 ### Rule #3: API Gateway Contract
 The HTTP/Gateway layer must perform strict request/response validation using `api/contract.zod.ts` and `api/endpoint.zod.ts`.
-- Incoming requests -> Validate `RequestEnvelope`
-- Outgoing responses -> Wrap in `ResponseEnvelope`
+- **Incoming requests** -> validate the body against the schema the operation
+ declares. There is no single request envelope, by design: `StandardApiContracts`
+ maps each standard operation to its `input` — `create` to `CreateRequestSchema`,
+ `update` to `UpdateRequestSchema`, `get` and `delete` to `IdRequestSchema`, the
+ `bulk*` family to `BulkRequestSchema`, `list` to `QuerySchema` (that one from
+ `@objectstack/spec/data`). The route's own shape — method, path, mappings — is
+ `ApiEndpointSchema` in `api/endpoint.zod.ts`.
+- **Outgoing responses** -> emit the one declared envelope. `BaseResponseSchema`
+ is its skeleton (`success`, `error`, `meta`); each response type adds its own
+ `data` on top of it — `SingleRecordResponseSchema`, `ListRecordResponseSchema`,
+ `BulkResponseSchema`, `DeleteResponseSchema` — and `StandardApiContracts` names
+ the `output` for the operation you served.
+```typescript
+import {
+ StandardApiContracts,
+ BaseResponseSchema,
+ envelopeViolations,
+} from '@objectstack/spec/api';
+```
+`BaseResponseSchema.safeParse` alone does NOT prove a body is envelope-conformant:
+it is a plain object schema, so it strips unknown keys, and it accepts
+`{ success: true }` carrying no payload at all. Gate what you emit with
+`envelopeViolations(body)` — it returns every way the body departs from the
+declared envelope, and an empty array means conformant.
 
 ### Rule #4: Event Driven Architecture
 System state changes (User created, Schema changed) MUST emit events defined in `EventSchema`.