fix(docs): the schema-extension FAQ rotted in reverse — pin the claim in the checked block this time

[os-zhuang]

Re-audit of the open items from the #3714 → #3890 thread against current main. Most resolved themselves — the #3896 close-out removed the remaining tool/flow/view dead keys, verifiedAt adoption went from 3 to 224 dated entries, and the FieldSchema declaration/runtime divergence dissolved outright. One item inverted into new rot, and it's mine.

The reversal

#3890 fixed a FAQ that recommended FieldSchema.extend() when FieldSchema was a ZodPipe (.extend was undefined). The fix taught: all three schemas are pipes, .extend throws, use .in for the inner object.

Every one of those claims is now false on main. Protocol 17 (#3855, acbf364a0) retired the deprecated aliases whose lowering was the whole reason for the field/object transforms — no aliases, no transform, and the pipes collapsed to plain ZodObjects. Verified against a clean build:

FieldSchema   bound ZodObject  .extend: function   .in: undefined
ObjectSchema  bound ZodObject  .extend: function   .in: undefined
ActionSchema  bound ZodPipe    .extend: undefined  .in: ZodObject

So the FAQ's .extend warning was wrong again, and its recommended FieldSchema.in was now the call that throws. The doc rotted in reverse, within days — the same "a claim with a timestamp, code moves under it in both directions" failure this whole thread has been unwinding, this time against my own fix.

Why the gate didn't catch it

#3890's checked block deliberately used only .parse() — shape-agnostic, after CI rejected the .in.extend attempt (the DTS/runtime divergence, since dissolved). That made the code durable and left the prose as the only load-bearing surface. Prose is exactly where rot settles: the gate compiles code, not claims.

The fix — move the claim into the checked block

The rewritten FAQ's checked example now calls FieldSchema.extend({ … }) directly. If the schema ever grows a transform again, .extend vanishes and CI goes red — the tripwire the prose could never be. Alongside it:

• composition (FieldSchema.parse + validate additions) stays as the shape-agnostic default;
• ActionSchema is documented as the pipe case (its requiresFeature → visible lowering is still live per the ledger), with the .in.extend skips-the-transform caveat;
• the FAQ teaches the one-line probe — typeof SomeSchema.extend === 'function' — instead of a table of shapes that history says will not stay true, and says openly that this page got it wrong twice.

Verification

• pnpm --filter @objectstack/spec check:skill-examples — ✅ 202 prose examples type-check (includes the new direct-.extend block).
• Runtime: FieldSchema.extend(...).parse(...) executes and returns the extended key; ActionSchema confirmed ZodPipe / .extend undefined / .in ZodObject — every claim in the rewritten FAQ was executed, not just type-checked.
• pnpm check:doc-authoring — 215 files clean.

Re-audit summary (the rest of the old list)

Item	Status on current main
tool dead props (category/permissions/active/builtIn)	removed by the #3896 close-out — done
verifiedAt backfill	224 dated (was 3) — actively adopted, no push needed
FieldSchema DTS/runtime divergence	dissolved by #3855 (schema genuinely a ZodObject now)
docs-drift bot symbol-level matching	still package-name heuristic (affected-docs.mjs) — worth an issue, not a drive-by
form-widget-resolution proof	still the one proofless high-risk class
example-harness paths beyond @objectstack/spec	still spec-only
undoable in-browser dogfood	still open; evidence pinned at objectui @732b1bf, verifiedAt within window

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 2, 2026 10:01am