docs(reference): document httpSurface, the redaction trio, and the token parsers

[rejifald]

Seven value exports on the stitchapi root barrel appeared on no page under apps/docs/content/docs — not in Reference, not in any guide:

Export	Source	Status before
httpSurface	./surface	undocumented (graphqlSurface / verdictOf had one mention each)
registerSecretKey, isSecretKey, redactSecretsDeep	./util	undocumented
duration, size, rate	./util	undocumented

Are any of them internal-but-exported?

No — that was the first thing checked, and all seven are deliberately public with a written reason. The barrel comments in packages/core/src/index.ts argue each one, and public-api-surface.spec.ts pins the parsers and verdictOf present while pinning classifyStatus / httpInterpret absent ("three names on the barrel for one decision invites composing the wrong one"). So all seven are documented, on the Reference pages that already own their neighbours — no new pages, no manifest entries beyond a description re-sync.

What changed

reference/helpers.mdx — two new sections:

• Secret redaction — the trio, framed off the denylist they widen (exact names vs. contained stems), with apiKey({ in: 'query', name })'s automatic registration named as the reason most callers never touch the manual hook.
• Duration, size, and rate tokens — the three grammars (CONTRACT.md P17/P25), each tied to the fields it actually backs (timeout.total, cache.ttl, circuit.cooldown · serve.body.max, @stitchapi/shell's buffer.max · throttle.rate), plus why rate.parse throws where the other two fall back to undefined: a cap's fallback leaves the ceiling where it was, but a rate's would silently remove the limit. Both directions are documented — see the note on the stacked core change below.

reference/surfaces.mdx — a httpSurface subsection under "http — the default": the default as a named value (compose resolves an omitted kind to it, so __config.kind is never an empty slot), and the one place importing it earns its keep — kind: httpSurface opting a member out of a surface inherited via extends. This page was also the only Reference page with no See also (AUTHORING rule 7); it has one now.

Reviewer notes

Three anti-pattern callouts (AUTHORING rule 10), the first two from behaviour verified against the built runtime, not inferred from source:

• isSecretKey('authorization') and isSecretKey('x-api-key') are false. Headers are scrubbed against a separate denylist (redactHeaders), so reaching for this predicate as a header check silently under-redacts. This is the one finding here I'd most want a second pair of eyes on.
• size on a *.chars field is a category error — stream.buffer.chars / trace.body.chars count UTF-16 code units of decoded text, not bytes off the socket. This one got sharper under the rename: the old parseBytes said "bytes" at the call site and size does not, so the type is now the only thing warning the reader.
• Don't compose httpSurface.interpret into your own surface — it ends in "the body is the value", the http surface's own choice of result. Compose verdictOf instead. This is exactly the mis-composition the barrel comment warns about.

Two adjacent fixes the sweep turned up:

• guides/resilience/throttle.mdx linked "duration token" at /docs/reference/config-types, a page that says nothing about the grammar. It now points at helpers#parseduration, which does (rule 6, one source of truth per fact).
• The manifest description for reference/helpers was stale; re-synced.

Known gap left out of scope: registerSecretKey / isSecretKey / redactSecretsDeep are not in the FUNCTIONS pin list in packages/core/test/public-api-surface.spec.ts, so an accidental removal of the trio would still slip past the suite. Deliberately not fixed here rather than widening a docs-only diff into core's tests; being handled separately.

Stacked on the core rename

The three parsers this page was written to document became parse/format pairs while this
PR was open — parseDuration/parseBytes/parseRate are now duration/size/rate, one
namespace per dimension, in the shape bytes uses. That core change is merged into this branch so
twoslash has a surface to check against; it drops out of this diff once it lands on main.
Review it as a stack — the core commit first, this docs commit second.

The three subsections are written against the new API and gained the encode direction:

duration.format(90_000); // '1.5m'
size.format(1537); // '1537b' — '1.5009765625kb' is exact and useless
rate.format({ count: 2, per: 1000 }); // '2/s'

format is the exact inverse of parse — parse(format(v)) returns v unchanged — which is
the clause the page leans on when it says a token is safe to write back. It is also where these
differ from ms, whose ms(90_000) is '2m' and reads back as 120 000.

One new anti-pattern callout came with the new direction rather than with the rename: format is
for values a person reads or re-authors, never for an emitted field. Every emitted duration stays
a raw-ms number (P17's complement), and formatting one into a payload turns a number every reader
can use into a string each of them has to parse.

The known gap named below is now closed — public-api-surface.spec.ts pins duration/size/
rate present as parse/format pairs, pins the three old names absent, and the redaction trio is
no longer the only unpinned group. That landed with the core change, not here.

Gates

Gate	Result
pnpm test (apps/docs)	69 passed, 1 skipped
pnpm check:types (apps/docs)	clean
pnpm check:docs-links	116 routes, all resolve
pnpm check:format	clean
pnpm gen:docs	no-op (0 stubs, no diff)

Re-verified after the rename: the real next build ran end to end on the merged branch, so twoslash type-checked every block against the new surface, and it was confirmed non-vacuous by putting a stale parseDuration import back into one block and watching the build fail on it. Twoslash runs at next build, not in the gates above, so all 25 blocks on the three edited pages were first run through createTwoslasher with the drafts-twoslash.spec.ts config — 25/25 green, and the harness was confirmed to fail a deliberately broken block rather than pass vacuously. The pre-push build-docs hook then ran the real next build end to end, so twoslash has since verified them for real.

🤖 Generated with Claude Code

[rejifald]

Stacked on #753 (feat(core)!: the token grammars become parse/format pairs), which is now open against main.

#753 is merged into this branch so twoslash has a surface to check against — that is why the core files show up in this diff. Merge #753 first; those commits drop out of here once it lands, leaving this PR docs-only as intended.