Skip to content

docs(contract): P4's violations and §6's backlog shipped — reconcile them - #548

Merged
rejifald merged 3 commits into
mainfrom
worktree-contract-p4-stale-backlog
Jul 31, 2026
Merged

docs(contract): P4's violations and §6's backlog shipped — reconcile them#548
rejifald merged 3 commits into
mainfrom
worktree-contract-p4-stale-backlog

Conversation

@rejifald

Copy link
Copy Markdown
Owner

The contract advertises work that is already done. P4 lists four live violations — all four
shipped — and §6's own Shipped record, sitting a few lines below its backlog table, already
says so. The two halves of the same section contradict each other, which makes the rule read
as one nobody enforces.

Complements #528: that PR reconciles the violation lists on P3/P5/P7/P8/P9/P14/P16/P17/P20 and
leaves P4 and §6's table untouched. This is those two.

P4 — verified against source, not against the record

Listed violation Reality
ReconnectOptions.maxAttemptsattempts shipped; maxAttempts survives only as engine.ts's resolved reconnect policy
CacheConfig.maxEntriesentries shipped; cache.ts reads config.entries, maxEntries is a local
CircuitOptions.failureThresholdfailures shipped with the P17 CircuitOptions overhaul; resilience.ts reads opts.failures, failureThreshold is a local
paginate.maxpages shipped, on the extracted PaginateOptions

Three of the four leave a max*/*Threshold name behind on a resolved internal, and that
pattern is the rule's own boundary — so P4 now states it rather than leaving the next reader to
grep and wonder: a max* spelling names a computed value; P4 governs the authoring surface.

§6 — seven of eight rows shipped

Only bodyKind (from-curl) is still live (from-curl.ts:24), so the table is down to that row.
The rest are recorded in §6's Shipped list below it; each verified in source:

  • cross-package StitchStore/StitchLike/RequestSeam clashes — qualified per-framework
    (SolidStitchStore, SvelteStitchStore) and per-ecosystem (ExpressRequestSeam, …); the
    ratchet's UNIQUE_WATCH de-listed StitchLike with a written rationale
  • queryOptionsstitchQueryOptions across all five framework bindings
  • OAuth2Opts/CookieSessionOptsOAuth2Options/CookieSessionOptions
  • anonymous paginate shape → exported PaginateOptions
  • SSE helper → streamStitchSse (the old names appear in no src/)
  • error-options → StitchErrorOptions
  • RedisDriver async closequit survives only on the upstream client duck-types, which
    P18 keeps at their upstream
    spelling, so the house contract is conformant

Deliberately not touched

The "New shorthand/toggle slots to add" line below the table (.inspect() scalars,
idempotency boolean, throttle string). throttle: string looks shipped — seam.ts folds it
via envelope(t, 'rate') — but the other two need the same per-item verification, and #528 is
already editing P12/P13/P20 territory. Left for a follow-up rather than guessed at here.

Verification

  • docs-only; no source, no type, no runtime change
  • contract ratchet 0 violations; check-docs-links green (110 routes)
  • prettier clean; full-tree pre-push gate green

🤖 Generated with Claude Code

rejifald and others added 3 commits July 31, 2026 18:16
…them

The doc advertised work that is done. P4 listed four live violations; all four
landed, and §6's own "Shipped" record below the table already says so — the two
halves of the same section contradicted each other.

Verified against source, not against the record:

- `ReconnectOptions.maxAttempts` → `attempts` (`maxAttempts` survives only as
  engine.ts's resolved reconnect policy)
- `CacheOptions.maxEntries` → `entries` (cache.ts reads `config.entries`;
  `maxEntries` is a local)
- `CircuitOptions.failureThreshold` → `failures` (resilience.ts reads
  `opts.failures`; `failureThreshold` is a local)
- `paginate.max` → `pages`, on the extracted `PaginateOptions`

That pattern is itself the rule's boundary, so P4 now states it: a `max*`
spelling is fine on a RESOLVED internal, which names a computed value; P4
governs the authoring surface.

§6's table had the same rot — seven of its eight rows shipped (the cross-package
clashes are qualified per-framework/per-ecosystem, `stitchQueryOptions`,
`OAuth2Options`/`CookieSessionOptions`, `PaginateOptions`, `streamStitchSse`,
`StitchErrorOptions`, and `RedisDriver`'s async `close` — `quit` survives only on
the upstream client duck-types, which P18 keeps at their upstream spelling).
Only `bodyKind` (from-curl) is still live, so the table is down to that one row.

Complements #528, which reconciles the other principles' violation lists but
leaves P4 and §6's table untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…en entry

#528 renamed §6 from "Migration backlog" to "Migration record", which broke both
`(#6-migration-backlog)` links — the one this branch added under P4 and the one
#528 left behind at P19. Both now point at the real heading.

Also reconciles §6's intro with its new name (it still promised "proposed target
spellings the sweep will apply" under a heading that says record), and states
what the one surviving row actually is: `bodyKind` lives in `from-curl.ts`,
imported by `cli.ts` alone, exported from no index and behind no subpath — so
nothing on the published surface carries the name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@rejifald
rejifald merged commit 5d6dea8 into main Jul 31, 2026
12 checks passed
@rejifald
rejifald deleted the worktree-contract-p4-stale-backlog branch July 31, 2026 17:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant