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

[os-elon]

Fixes#9614

packages/spec/prompts/implement-objectos.md Rule #3 told an agent implementing the
runtime kernel to "Validate RequestEnvelope" and "Wrap in ResponseEnvelope".
Neither is an export of @objectstack/spec. This is a published prompt whose audience
is AI authors, so a fabricated name in prose is read as authoritative and copied into an
import by whoever follows it.

Premise re-verified before editing

Re-measured on the file as it stands after #9615 (890b38f, the same-day churn on this
exact file), not on the card's snapshot:

Symbol	In any of the 16 published api-surface/*.json	In the built .d.ts
RequestEnvelope	no	no
ResponseEnvelope	no	no

ResponseEnvelopeConfig / ResponseEnvelopeConfigParsed / ResponseEnvelopeConfigSchema
do exist in ./api, but they configure an envelope rather than being one, so the card was
right that they are not a drop-in referent.

What Rule #3 now names, and why

The choice was between inventing one referent and describing the surface the package
actually has. packages/spec/src/api/contract.zod.ts deliberately has several shapes
on the request side and one skeleton plus per-route extensions on the response side, so
the rule is reworded to say that rather than to point at a single symbol that would have
had to be created. Nothing was added or aliased in packages/spec/src/**.

Requests — there is no single request envelope, by design. StandardApiContracts
(section 4 of contract.zod.ts) maps each standard operation to its input: create to
CreateRequestSchema, update to UpdateRequestSchema, get and delete to
IdRequestSchema, the bulk* family to BulkRequestSchema, and list to QuerySchema
(that one from @objectstack/spec/data, stated in the prose because the entrypoint
differs). The rule also now reaches ApiEndpointSchema, which makes
api/endpoint.zod.ts — a file the rule already cited in its opening sentence — actually
referenced by one of its bullets instead of cited and then unused.

Responses — BaseResponseSchema is the real name of the response envelope, and its
own docstring says the thing an implementer most needs and would otherwise get wrong:
it is a plain z.object, so safeParse alone does not prove a body is
envelope-conformant. It strips unknown keys and accepts { success: true } carrying no
payload — which is how { success: true, data: link, link } shipped undetected in the
share-links dispatcher. envelopeViolations(body) is the check that answers "is this
actually the declared envelope", and the rule now sends the reader there. The concrete
bodies (SingleRecordResponseSchema, ListRecordResponseSchema, BulkResponseSchema,
DeleteResponseSchema) are named as the extensions that add data.

The referents moved from prose into a fenced import — on purpose

The card notes why this defect survived every sweep: check:published-readme-exports
resolves import { ... } from '...' clauses and X.member( call sites, and a bare symbol
name in a bullet matches neither. Rule #3 now carries a fenced typescript import of
StandardApiContracts, BaseResponseSchema and envelopeViolations, so the three
load-bearing referents are inside the gate's coverage from now on. That does not close the
structural blind spot — prose symbols are still invisible, and that stays #9532's lane —
but it does mean this particular rule can no longer drift silently.

Verification

Every symbol Rule #3 names in prose was resolved against the built type surface, the
way the card measured. Full gate union at 26b33cf, on a fully built workspace
(pnpm build, 71/71 tasks) — 15/15 pass, including the two the dispatch mandated
regardless of derivation:

check:empty-state · check:liveness · check:strictness-ledger · check:variant-docs
check:merge-driver · check:type-source-resolution · check:changeset-gate-self-tests
check:objectui-changeset · check-dev-prereqs · check-affected-docs
check-adr-0087-registration · check-changeset-no-major · check-empty-changeset
check-published-readme-exports · check-nul-bytes

✓ check:published-readme-exports — 60 published document(s) across 77 workspace
package(s); 189 import statement(s), 49 workspace type entr(ies).
0 known instance(s) still in scripts/published-readme-exports.baseline.json

Reverse verification. Renaming one symbol in the new fence to envelopeViolationz
turns the gate red on exactly that symbol and nothing else, which is the evidence that the
fence is genuinely inside the gate's coverage rather than merely green:

✗ check:published-readme-exports — 1 undocumented symbol claim(s)
packages/spec/prompts/implement-objectos.md
key: @objectstack/spec|packages/spec/prompts/implement-objectos.md|import|@objectstack/spec/api|envelopeViolationz

Restoring the symbol returns the gate to green, and the marker's absence was confirmed
before the restored leg was read. Markdown is not compiled, so the artifact the gate reads
is the source file itself; @objectstack/spec was built once beforehand and unchanged
across both legs, and the mutation leg proves the gate was reading the edited bytes.

One note for whoever runs these locally: on an unbuilt tree
check:published-readme-exports reports the missing dist/ entries and returns before it
reaches any finding, so it cannot verify or falsify a change like this until
pnpm build has run. Both legs above were measured after a full build.

Scope

One prompt file plus its changeset. Rule #4's EventSchema and workflow step 3's
ApiRoutesSchema were verified real and left untouched, as the card asked; the rest of the
file is not restyled. No schema, runtime behaviour or authorable surface changes, so the
changeset is patch.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

Nothing in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)), so this run has no opinion about the docs.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/spec/prompts/implement-objectos.md) — pages documenting those are invisible to this run

Coarse fallback — 115 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 2b292ce912d9c15a113786eb58e5e77f8b1981ca → packageMentionDocs.