Versioning primitives v2: client pinning, error shaping, introspection, behavior catalogs

[mahmoudimus]

Summary

46 commits extending tsadwyn with the primitives real production adopters were hand-rolling on top of the framework: Stripe-style per-client pinning, server-driven error envelope versioning, introspection/debugging tools, typed per-version behavior catalogs, and a pre-wired /versioning upgrade resource. Consolidates the patterns from consumer integrations into first-class library surface.

Fixes #1 #2 #3.

⚠️ Breaking change

• migrateHttpErrors now defaults to true (was false). Matches Stripe's actual production behavior: response migrations apply to 4xx/5xx error bodies unless explicitly opted out via { migrateHttpErrors: false }. Rationale and migration path in the README's Versioning error responses section. Consumers currently on false need to pass it explicitly or accept the new behavior.

New primitives

Client pinning (the Stripe model, productized)

• perClientDefaultVersion({ identify, resolvePin, fallback, pinOnFirstResolve?, supportedVersions?, onStalePin? }) — canonical DB-backed default-version resolver
• cachedPerClientDefaultVersion({ ..., ttlMs }) — high-QPS variant: TTL'd map, single-flight first-miss, explicit { resolver, invalidate, invalidateAll } handles
• preVersionPick option on Tsadwyn — auth middleware runs before the default-version resolver
• onUnsupportedVersion: 'reject' | 'fallback' | 'passthrough' on versionPickingMiddleware
• createVersioningRoutes({ identify, loadVersion, saveVersion, supportedVersions }) — pre-wired RESTful /versioning resource with optimistic concurrency via {from, to} payloads
• validateVersionUpgrade({ from, to, supported, ... }) — pure upgrade-policy helper with discriminated-union result

Per-version behavior (not just schemas)

• createVersionedBehavior({ head, changes, initialVersion? }) — typed overlay primitive; behaviorHad: Partial<Behavior> is compile-time-checked against the head shape
• buildBehaviorResolver(map, fallback, opts?) — low-level escape hatch for one-off maps
• VersionChangeWithSideEffects.isApplied — boolean toggle for single-axis behavior changes

Error shaping

• errorMapper option on Tsadwyn — translate domain exceptions → HttpError inside the handler catch block
• exceptionMap({ ErrorClass: { status, body } }) + isExceptionMapFn — declarative, introspectable map form
• ValidationError extends HttpError — Zod validation failures flow through errorMapper + migrateHttpErrors like any other error

Handler-level escape hatches

• currentRequest() / currentRequestOrNull() — read the raw Express Request from inside any handler or migration callback. Auto-captured by the dispatcher — no middleware to mount.
• requestContextStorage — underlying ALS, exported for advanced use

Generation-time diagnostics

• detectRouteShadows(routes) + reportRouteShadows(shadows, policy, logger?) — wildcard-before-literal detector
• onRouteShadowing: 'warn' | 'throw' | 'silent' + routeShadowingLogger on Tsadwyn
• Generation-time lint now also catches: statusCode: 204 with body schema, body-mutating migrations on body-less responses, response migrations against raw() routes, GET/HEAD duplicates

Non-JSON response helpers

• raw({ mimeType, supportsRanges? }) — schema marker for binary/streaming routes; marks body-migrations against this route as dead code
• deletedResponseSchema(objectName, extraFields?) — Stripe-style {id, object, deleted: true} helper (pair with statusCode: 200 — 204 strips the body at the wire)
• Router HEAD method support + tags: string[] in RouteOptions
• 204/HEAD short-circuit in the dispatcher skips body migrations and wire emission

Outbound payload migration

• migratePayloadToVersion(schemaName, payload, targetVersion, bundle) — standalone helper for webhooks and internal events (same migrations as in-flight dispatch, but invoked outside the request path)

Introspection / debugging trio

• dumpRouteTable(app, opts?) — per-version route enumeration
• inspectMigrationChain(app, { schemaName, clientVersion, direction }) — ordered migration chain for a schema + pin
• simulateRoute(app, { method, path, version, body? }) — simulate a request without dispatching: matched route, candidate diagnostics, fallthrough reasons, up-migrated body preview

CLI

New subcommands on the tsadwyn binary:

• routes --app <path> — route table with version filtering
• migrations --app <path> --schema <name> --version <value> — migration chain for a schema+pin
• simulate --app <path> --method <M> --path <p> [--version <v>] [--body <json>] — incident-triage tool
• exceptions --app <path> — render the errorMapper / exceptionMap table
• new version --date <YYYY-MM-DD> — scaffold a new VersionChange file

Docs

README grew from ~265 → ~996 lines. New sections:

• Client pinning — explicit header / per-client default / cachedPerClientDefaultVersion high-traffic variant / stale pins rationale
• Versioning error responses — the migrateHttpErrors default flip + errorMapper + exceptionMap interaction
• Versioning behavior changes — VersionChangeWithSideEffects, createVersionedBehavior typed overlay, buildBehaviorResolver escape hatch
• Upgrade semantics — the /versioning resource — optional, persistence-free adapter with {from, to} optimistic-concurrency
• Reading the raw request — currentRequest() — stripped-handler-view rationale + escape-hatch pattern
• Route shadowing — the first-match-wins trap — detection heuristic + policy table
• Adopting tsadwyn incrementally alongside existing Express routes
• API Reference tables rebuilt to cover all new exports

Working end-to-end examples in examples/stripe-api.ts and examples/task-api.ts.

Test plan

• npm run typecheck — clean
• npm run build — dual ESM/CJS + .d.ts + .d.mts emission successful
• npm test — 860/860 passing (56 test files). 2 supertest-related tests exhibit pre-existing intermittent flake at ~20% per-file rate under parallel forks; flake predates this branch and is documented in CLAUDE.md (root cause: supertest + Node HTTP keep-alive state; ecosystem pattern, not regression). See _gitless/testing-flakiness-research.md.
• Full GPG-signed commit history
• CI to be verified post-push (Node 20/22/24 matrix)
• Manual verification of CLI subcommands against examples/stripe-api.ts

Migration notes for existing consumers

1. migrateHttpErrors: false where needed — grep convertResponseToPreviousVersionFor call sites. If a migration should NOT apply to error bodies, add { migrateHttpErrors: false } explicitly.
2. Null-safety on schema-scoped migrations — they may now fire on error-envelope shapes ({ detail: ... } validation errors) that don't match the schema. Null-check fields before mutating. See the defensive pattern snippet in the README.
3. headerOnly: true — a new orthogonal flag for migrations that only mutate headers (not body). Runs on 204/304/HEAD body-less responses without NPE'ing.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR expands tsadwyn’s versioning surface to include Stripe-style client pinning, error-envelope shaping, per-version behavior catalogs, and a set of introspection/debugging tools (plus a pre-wired /versioning resource), while also flipping the default for migrateHttpErrors to true.

Changes:

• Add new primitives: per-client default version resolvers (including cached variant), per-version behavior overlays, /versioning routes + upgrade-policy helper, raw/binary response marker, and deleted-response schema helper.
• Add introspection tooling: route-table dump, migration-chain inspection, route-shadowing detection/reporting, and request-context accessors.
• Update middleware/error pipeline semantics (notably migrateHttpErrors default = true) and extend route registration options (tags, HEAD).

Reviewed changes

Copilot reviewed 58 out of 70 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
tests/versioned-behavior.test.ts	New tests for createVersionedBehavior overlay semantics and unknown-version behavior.
tests/route-shadowing.test.ts	Tests for route-shadowing detection + Tsadwyn integration policies.
tests/response-types.test.ts	Adjusts tests for new migrateHttpErrors default (explicit opt-out).
tests/migration-coverage.test.ts	Adjusts error-migration coverage tests for new default (explicit opt-out).
tests/issue-wildcard-route-collision.test.ts	Regression test covering wildcard-before-literal collisions (shadowing).
tests/issue-validation-error-envelope.test.ts	Tests ValidationError flowing through error pipeline + migrations/mapper.
tests/issue-validate-version-upgrade.test.ts	Tests for validateVersionUpgrade policy helper.
tests/issue-route-table-dump.test.ts	Tests for dumpRouteTable route enumeration/filtering.
tests/issue-route-options-tags.test.ts	Tests for RouteOptions.tags registration + OpenAPI emission/mutation.
tests/issue-raw-response.test.ts	Tests for raw() marker behavior + dead-migration warning semantics.
tests/issue-pre-version-pick-hook.test.ts	Tests for preVersionPick ordering, error propagation, and composition.
tests/issue-on-unsupported-version.test.ts	Tests for onUnsupportedVersion behavior in versionPickingMiddleware.
tests/issue-migration-chain-inspector.test.ts	Tests for inspectMigrationChain ordering and filtering semantics.
tests/issue-migrate-payload-to-version.test.ts	Tests for migratePayloadToVersion (out-of-band payload reshaping).
tests/issue-head-requests.test.ts	Tests for explicit HEAD support + HEAD migration short-circuit semantics.
tests/issue-error-mapper.test.ts	Tests for TsadwynOptions.errorMapper mapping domain errors to HttpError.
tests/issue-cli-introspection-subcommands.test.ts	Tests for CLI runners for routes/migrations/simulate.
tests/issue-build-behavior-resolver.test.ts	Tests for buildBehaviorResolver unknown-version telemetry behaviors.
tests/issue-204-body-lint.test.ts	Tests generation-time lint for 204-with-body schema footgun.
tests/http-errors.test.ts	Updates response-migration tests for migrateHttpErrors default flip.
tests/fixtures/cli-migrations-app.ts	CLI fixture app with real migration for migrations/inspection commands.
tests/fixtures/cli-exception-map-app.ts	CLI fixture app for exception-map introspection command.
tests/delete-response-helper.test.ts	Tests deletedResponseSchema helper + version-migration behavior.
tests/data-coverage.test.ts	Updates expectations for migrateHttpErrors default = true.
tests/current-request.test.ts	Tests currentRequest()/ALS request context plumbing and isolation.
tests/cached-per-client-default.test.ts	Tests TTL cache, invalidation, and single-flight per-client default resolver.
tests/basic.test.ts	Defensive migration update acknowledging error-body migrations now default on.
src/versioning-routes.ts	Adds createVersioningRoutes helper implementing /versioning GET/POST contract.
src/versioned-behavior.ts	Adds createVersionedBehavior typed overlay builder + snapshot map.
src/version-upgrade.ts	Adds validateVersionUpgrade helper with iso-date/semver/custom comparator support.
src/structure/data.ts	Adds headerOnly option; flips migrateHttpErrors default to true; threads flags into instructions.
src/router.ts	Adds RouteOptions.tags + tag warnings/dedup; adds explicit .head() registration.
src/route-table.ts	Adds dumpRouteTable introspection helper with filtering options.
src/route-shadowing.ts	Adds route-shadowing detection + reporting with warn/throw/silent policies.
src/request-context.ts	Adds currentRequest()/currentRequestOrNull() and exported ALS storage.
src/raw-response.ts	Adds raw() marker + detection helper for binary/streaming responses.
src/per-client-default.ts	Adds perClientDefaultVersion resolver helper with caching + stale-pin policies.
src/migration-chain.ts	Adds inspectMigrationChain introspector for request/response migrations.
src/migrate-payload.ts	Adds migratePayloadToVersion helper for outbound payload reshaping.
src/middleware.ts	Adds onUnsupportedVersion policy + error handling around default resolver.
src/index.ts	Exports new primitives/helpers/introspection utilities.
src/exceptions.ts	Adds ValidationError as HttpError subclass for validation failures.
src/exception-map.ts	Adds exceptionMap + isExceptionMapFn for declarative/introspectable error mapping.
src/delete-response.ts	Adds deletedResponseSchema helper for Stripe-style delete responses.
src/cached-per-client-default.ts	Adds cached per-client resolver variant with TTL + invalidation.
src/behavior-resolver.ts	Adds buildBehaviorResolver helper for per-version behavior lookup.
src/application.ts	Wires preVersionPick hook, errorMapper injection, and route-shadowing policy into Tsadwyn initialization/generation.
coverage/sorter.js	Removes committed coverage artifact.
coverage/prettify.css	Removes committed coverage artifact.
coverage/index.html	Removes committed coverage artifact.
coverage/block-navigation.js	Removes committed coverage artifact.
coverage/base.css	Removes committed coverage artifact.
.gitignore	Adds ignores for local-only design/spec artifacts (and related docs).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In the 409 version_mismatch response, the expected/actual fields look reversed: expected is currently set to the client-sent from, and actual is set to the server’s effective stored/fallback version. Typically expected should be the server’s effective version and actual should be what the client sent, so clients can reconcile and retry correctly.

[Copilot]

latest: opts.supportedVersions[0] assumes supportedVersions is non-empty. If a consumer passes an empty list (or misorders it), this returns undefined but the Zod schema requires a string. Consider validating supportedVersions.length > 0 up front (and/or deriving latest more defensively).

[Copilot]

This file still claims the export is missing and uses @ts-expect-error to force a failing import, but validateVersionUpgrade is now exported from src/index.ts. Please remove the stale “FAILING TEST”/“GAP” comments and the @ts-expect-error so the test reflects the current intended behavior.

[Copilot]

dumpRouteTable is now exported from src/index.ts, but this test still includes “GAP: not exported” and an @ts-expect-error on the import. Please remove the @ts-expect-error and update the header comment (it no longer represents a failing-gap test).

[Copilot]

raw is now exported from src/index.ts, but this test still marks the import with @ts-expect-error and describes it as a missing export. Please drop the stale “GAP”/“FAILING TEST” framing and remove the @ts-expect-error so the test doesn’t mislead future readers.

[Copilot]

buildBehaviorResolver is now exported from src/index.ts, so the @ts-expect-error and “GAP: … not exported” comment are stale/misleading. Please remove them and treat this as a normal behavior test.

[Copilot]

runRoutes/runMigrations/runSimulate are exported from src/cli.ts, but this test still labels them as missing and uses @ts-expect-error on the import. Please remove the stale “GAP” framing and the @ts-expect-error so the test reflects the current public API.

[mahmoudimus]

Copilot review — triage

Addressed in two commits on this branch:

✅ Fixed — supertest: supportedVersions: [] produced latest: undefined

15c291b (fix) — Validates up-front in createVersioningRoutes(...); an empty or missing supportedVersions now throws a clear Error at construction with a message pointing at the typical fix (bundle.versionValues). Previously the misconfiguration would surface at dispatch as a cryptic Zod "expected string, got undefined" error far from the actual cause. Added two tests covering the guard (empty array + explicitly-undefined).

✅ Fixed — stale @ts-expect-error / "GAP" framing across 11 test files

e894bd8 (chore/tests) — Copilot flagged 5 files with stale @ts-expect-error pragmas on imports that now work. While we were in there I grepped for the same pattern across all tests and found 6 more with the identical stale framing; cleaned them all up for consistency. Each file now has an accurate "Covers <primitive> ..." header instead of the original "FAILING TEST — verifies the gap..." language, and the fake-failing import block has been folded back into the main import.

Preserved intentionally: tests/versioned-behavior.test.ts:186 has a legitimate @ts-expect-error that asserts a compile-time contract on behaviorHad: Partial<Behavior>. That one's a real type guard, not stale framing.

❌ Not changed — 409 response expected / actual field naming

Copilot suggested swapping the fields in the 409 version_mismatch response body — claiming expected should be the server's effective version and actual should be the client-sent from.

I looked at this carefully and it's not a bug, it's a convention choice. The current semantic is client-perspective naming: "I (the client) expected the current state to be X (my last-known); actually it's Y (server's truth)." That's explicitly documented in README line 529 with a concrete example and asserted by two tests in issue-versioning-resource.test.ts at lines 158–159 and 322–323 — the second has an explicit // effective, not null comment on actual, showing the semantic was deliberate, not accidental.

Both namings (client-perspective vs server-perspective) are defensible. Swapping now would:

1. Invert the documented contract in the README
2. Break two existing tests
3. Be a silent breaking change for any consumer parsing these fields

Happy to revisit in a follow-up if there's a strong preference for server-perspective naming, but that'd be a deliberate v0.2.0 contract change, not a bug fix. Keeping the current shape here.

---

Result: npm run typecheck clean, npm test passing 862/862 (up from 860 — added 2 tests for the new guard). All commits GPG-signed with the same key as the rest of the branch.

[Copilot]

Pull request overview

Copilot reviewed 58 out of 70 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

In the 409 "version_mismatch" response, the expected and actual fields appear swapped: expected is currently set to the client-sent from, while actual is set to the server-side effective version. For optimistic concurrency, expected should reflect what the server expected (the effective version), and actual should reflect what the client sent, so callers can diagnose and retry correctly.

[Copilot]

The BuildBehaviorResolverOptions.logger docstring says the logger is "Required if onUnknown !== 'silent'", but the implementation treats it as optional (it simply skips warnings when logger is absent). Either enforce the requirement (throw when onUnknown is warn-* and no logger is provided) or update the documentation to match the actual behavior.

Suggested change

	/** Optional structured logger. Required if `onUnknown !== 'silent'`. */
	/**
	* Optional structured logger. When provided and `onUnknown !== 'silent'`,
	* unknown-version lookups may emit warnings; otherwise warnings are skipped.
	*/

[Copilot]

CreateVersionedBehaviorOptions.logger is documented as required when onUnknown !== 'silent', but createVersionedBehavior does not enforce this (it passes the optional logger through and warnings become a no-op). Consider either validating and throwing when onUnknown is warn-* without a logger, or relaxing the docstring to say warnings are only emitted when a logger is supplied.

[Copilot]

This file header still says "FAILING TEST" / "will turn green when…", but the PR implements errorMapper and the overall test plan claims the suite is passing. Consider updating this header to reflect that it's now a regression/coverage test (or remove the outdated wording) to avoid confusion for future contributors.

[mahmoudimus]

Copilot review — second round triage

✅ Fixed — logger required when onUnknown !== 'silent'

dd464fd (fix) — Copilot caught a real docstring/code mismatch on BuildBehaviorResolverOptions.logger. The docs claimed the logger was "Required if `onUnknown !== 'silent'`" but the implementation silently no-op'd warnings when it was missing. That's the worst kind of bug: user opts into telemetry (onUnknown: 'warn-once'), forgets the logger, never sees a warning, never knows why.

Now throws TsadwynStructureError at construction with an actionable message. Same guard flows transitively into createVersionedBehavior since it delegates telemetry options through. Added 4 new tests locking in the enforcement on both APIs — TDD-verified by reverting the guard and confirming all 4 fail (the non-throwing happy-path tests still pass in both states, which proves the guard is the specific behavior being tested).

✅ Fixed — stale "FAILING TEST" header on issue-error-mapper.test.ts

3ed1f66 (chore/tests) — same stale-header pattern I cleaned in e894bd8, but without the @ts-expect-error pragma my earlier grep was keyed on. grep -l "FAILING TEST" tests/ found 7 more files with the same issue; cleaned all 8 in one sweep.

❌ Not changed — 409 expected / actual swap (second time flagged)

This is the same suggestion from the first review pass. My reply there still applies:

• Current semantic is client-perspective naming: "I expected the current state to be X; actually it's Y."
• Documented in README line 529 with a concrete example.
• Asserted by 2 tests in issue-versioning-resource.test.ts, one with an explicit // effective, not null comment proving the choice was deliberate.
• Both namings (client-perspective vs server-perspective) are defensible. Swapping now would break the documented contract + invert the tests + be a silent breaking change for any consumer parsing these fields.

Leaving unchanged. Happy to revisit in a follow-up v0.2.0 if there's a strong preference for server-perspective naming, but it's a deliberate API choice, not a bug.

---

Result: npm run typecheck clean, npm test passing 869/869 (up from 862 — +4 logger-enforcement tests and +3 other delegation-locking tests). All commits GPG-signed.