refactor(api)!: contract freeze — hard-break sweep of the entire published surface#470
Open
rejifald wants to merge 4 commits into
Open
refactor(api)!: contract freeze — hard-break sweep of the entire published surface#470rejifald wants to merge 4 commits into
rejifald wants to merge 4 commits into
Conversation
… renames, shim purge Sweep of the entire published surface against docs/CONTRACT.md (P0–P23), maintainer-sanctioned hard break (no @deprecated aliases; pre-GA, few adopters): - core P0: __config is strictly JSON again — all function sugar (url thunks, transform, predicates, keyOf, paginate fns, hooks) lives on __rawConfig; RedactedStitchConfig narrowed; runtime regression spec added - core renames: query→document, unwrap→pick, cache.key()→keyOf(), SurfaceOutcome/CacheHit value→data, timing.ms→elapsed, otlpTrace→otlpSink, scope→tenancy, registerSecretKey/isSecretKey, maxBodyChars, serverInfo, graphql/sse/stream/download/llm binders → .bind, testing SseFixtureEvent - typing: StatusMatch (number|number[]|predicate) everywhere; T|T[] widenings; Scalar|AtLeastOne on every config slot (stream/multipart/sse/throttle/ idempotency/hooks/input/retry/timeout/circuit incl. [failures,cooldown] tuple + inspect(input,true)); StitchStore ttl optional on set AND incr; RateLimitError gains attempts/body/url (P10 parity) - every existing @deprecated shim + alias-parity test deleted repo-wide (rateLimit slot, throttle.scope, key fns, *Ms fields, value co-sets, bare queryOptions/RequestSeam/StitchHost, SchemaFingerprint.value, …) - packages: query-core hoists StitchQueryOptions (blessed TanStack mirror) + key derivation for all five bindings; StitchQueryState→StitchQueryResult; svelte drops useStitch* for stitchStore*; hosts converge on streamStitchSse + StitchErrorOptions with elysia SSE error-leak fix; next stitchErrorResponse → Response|undefined; stores del→delete + optional-ttl house contract; openapi generator apiKey emission fixed; shell responseType/maxBufferBytes; aws-sigv4 amzDate; json-schema AjvLike; fingerprint unwrap→pick - contract ratchet baseline shrunk to 0 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…CT.md rewrite, ratchet upgrades, SSE parity - apps/docs: all integration/guide/blog pages respelled to the canonical surface (document/pick/pool/tenancy/streamStitchSse/StitchErrorOptions/ StitchQueryResult/stitchStore/amzDate/…); unwrap guide renamed to pick (+ permanent redirect); playground presets, completions codegen, sandbox allow-list and demo scene updated; search golden follows the new slug - docs/CONTRACT.md rewritten to post-sweep reality: violation lists are now resolved-history, §6 is a migration record (alias-free hard break under maintainer waiver), P19 amended (pre-GA hard breaks sanctioned; deprecation cycle from GA), blessed carve-outs recorded (StitchQueryOptions TanStack mirror, StitchLike tiers, svelte stitchStore, P8 divergences, shared host shapes, redaction sentinels) - scripts/check-contract.mjs: R1 bans *Return/*State, R6 covers nested toggle slots (real finding fixed: mcp serverInfo → AtLeastOne), R5 watch-list refreshed with de-list rationales, new R7 flags any @deprecated on the published surface; baseline stays 0 - hosts: StreamStitchSseOptions widened to the express canonical shape (data(chunk, index), event string|fn) in fastify/nest/hono/elysia/next, with per-host tests - from-curl bodyType (last P1 stragglers), mcp tool description respelled Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- eval-harness prebaked snippets respelled (document/pick/pages/baseDelay) — the offline scorer was exercising the deleted surface - core bundle budget 24.80→25.25 / 20.00→20.40 KB, documented: scalar-shorthand normalization, StatusMatch matcher and P0 deep redaction outweigh the deleted shims by ~0.2 KB and cannot move to a subpath - README prettier pass Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
New normative rule P24 (+ ratchet R8 enforcing it): >=2 flat fields sharing
a leading-word prefix in a house-owned contract fold into one named,
exported, {}-rejecting envelope with a dominant-field scalar. Carve-outs:
foreign mirrors (TanStack queryKey/queryFn, RFC 6749 client*, XHR response*,
RTK lifecycle, Orama-schema DocSearchHit.page* — maintainer-exempted),
single-field collapse per P12, on*/is*/percentile conventions.
Conversions (hard break, per amended P19):
- OAuth2Options.refreshOn/refreshSkew → refresh: StatusMatch | { on, skew }
- CookieSessionOptions.refreshOn/refreshWhen → refresh: StatusMatch | { on, when }
- SentrySinkOptions.captureErrors/captureDrift → capture: boolean | { errors, drift }
- nest StitchFeatureOptions.seamConfig/seamToken → seam: { config, token }
(R8's first real catch, found during adoption)
Docs/blog/READMEs/AUTHORING respelled; ADR 0006 amended via callout;
contract baseline stays 0.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
rejifald
commented
Jul 8, 2026
| @@ -101,7 +101,7 @@ const me = stitch({ | |||
| loginInput: () => ({ | |||
Owner
Author
There was a problem hiding this comment.
We need a convention for these type of callbacks.
So it can accommodate both function and declaration
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The full pre-GA API freeze: every method name, prop name, and returned type across
stitchapicore (15 entry points) and all 32 published@stitchapi/*packages now matches docs/CONTRACT.md (P0–P23). Maintainer-sanctioned hard break — no@deprecatedaliases added, and every existing shim + alias-parity test deleted (pre-GA, few adopters; P19 amended accordingly).Driven by a 35-agent audit (17 scoped auditors + adversarial verification + coverage critic) that found ~95 deduplicated violations; all are addressed here.
Highlights
__configis strictly JSON again — url thunks,transform, predicates,keyOf, paginate fns, hooks all live on the non-enumerable__rawConfig;RedactedStitchConfignarrowed; runtime regression spec (contract-p0.spec.ts) pins zero fn-paths + lossless JSON round-trip.query→document,unwrap→pick,cache.key()→keyOf(),value→dataon every result envelope,scope→tenancy(auth),otlpTrace→otlpSink,del→delete,dateTime→amzDate,decode→responseType, all five authoring binders →.bind,StitchQueryState→StitchQueryResult,UseStitchReturn→UseStitchResult, svelte standardizes onstitchStore*, hosts converge onstreamStitchSse+StitchErrorOptions, plugin/middleware options framework-qualified.StatusMatch(number | number[] | predicate) on every status field;T | T[]widenings; every config slot isScalar | AtLeastOne<Options>({}is a compile error) with new scalar shorthands (stream:'ndjson',multipart:'dot',sse:true,throttle:'2/s',idempotency:true,circuit:[failures,cooldown],inspect(input,true));StitchStorettl optional onset/incr;RateLimitErrorcarries the full P10 field set.errorDataopt-in, matching all hosts); openapi generator emits type-correctapiKeyauth; nextstitchErrorResponsereturnsResponse | undefinedso?? throwcomposes; react/angular hooks no longer accept-and-ignore a streaming flag.StitchQueryOptions+ key-derivation (incl. secret-header redaction) single-sourced in@stitchapi/query-core(was byte-copied in 5 bindings);StitchEventSourceowned by core.StitchQueryOptionskeeps TanStack's own vocabulary;StitchLikerich/minimal tiers; P8 documented default divergences (oauth2/cookie tenancy, pino/sentry lifecycle, RN keyPrefix).unwrapguide →pickwith a permanent redirect; completions codegen regenerated.*Return/*State, R6 covers nested toggle slots, R5 de-lists documented, new R7 fails on any@deprecatedon the surface. Baseline: 0.Verification
All 12 gates green:
check:types,check:types-d,check:lint,check:format,check:contract(baseline 0),check:exports(+companions),check:size,check:docs-links,check:release, full workspace tests, and the apps/docs production build (twoslash-compiles every snippet).media-fresh note: pushed with
STITCH_MEDIA_STALE_OK=1. The demo scene's only changes are inside thepicksegment, which is not part of the recorded README cut (4-segment loop, verified frame-by-frame); a fullgen:mediare-render produced byte-identical assets (hash-verified), so the committed media is genuinely fresh — the path-based gate cannot express "regenerated, no diff".🤖 Generated with Claude Code