Audit: cross-package contract assumptions between core and downstream @askrjs packages

[smiggleworth]

Purpose

This is an audit task, not a bug report — it produces a contract table and spins off bugs, it doesn't fix anything itself.

Downstream packages (askr-ui, askr-server, askr-themes, askr-cli, askr-testing, etc.) build on core's public API and behavior. Nothing currently checks that what they assume about core actually matches what core guarantees. askr-themes shipping a Tabs stub because no working primitive exists underneath it in askr-ui is the sibling-package version of this exact gap — verify core's own contracts with its consumers are equally solid.

Procedure

1. In each downstream repo, grep for imports from @askrjs/askr (root and subpaths): grep -rn "from \"@askrjs/askr" ../<repo>/src.
2. For each imported symbol, note: what behavior/contract does the consumer appear to assume (error types thrown, timing guarantees, whether a callback can be called synchronously vs. only via scheduler, etc.)?
3. Cross-check that assumption against core's actual implementation and its docs.
4. Where the consumer's assumption doesn't match (or isn't documented anywhere as guaranteed), file a gap issue — either in core (if the guarantee should exist and doesn't) or in the consumer repo (if it's relying on unspecified behavior).

Definition of Done

• This issue's description contains a table: consumer repo | symbol imported | assumed contract | verified match (✅) or gap (🔗, with which repo the fix belongs in).
• Every downstream @askrjs/* repo that imports from @askrjs/askr has been checked.
• No row is left unmarked.

Audit results (2026-08-24)

The inventory below is parsed from TypeScript import declarations in each sibling package src/ tree (plus the website consumer), deduplicated by repo/module/symbol. Type-only imports assume declaration shape only. Runtime imports were cross-checked against the public declarations, API docs, ownership/scheduler tests, and the consuming call sites.

Consumer	Imported symbol	Assumed contract	Result
askr-charts	@askrjs/askr -> state	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-charts	@askrjs/askr/jsx-runtime -> JSXElement	JSX factory/types match the automatic runtime	✅
askr-i18n	@askrjs/askr -> defineScope	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-i18n	@askrjs/askr -> readScope	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-i18n	@askrjs/askr/foundations/structures -> JSXElement	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-logos	@askrjs/askr/foundations/icon -> IconBase	icon nodes/props follow the public SVG contract	✅
askr-logos	@askrjs/askr/foundations/icon -> IconProps	icon nodes/props follow the public SVG contract	✅
askr-logos	@askrjs/askr/jsx-runtime -> Fragment	JSX factory/types match the automatic runtime	✅
askr-logos	@askrjs/askr/jsx-runtime -> jsx as createSvgNode	JSX factory/types match the automatic runtime	✅
askr-logos	@askrjs/askr/jsx-runtime -> JSXElement	JSX factory/types match the automatic runtime	✅
askr-logos	@askrjs/askr/jsx-runtime -> jsxs as createSvgFragment	JSX factory/types match the automatic runtime	✅
askr-lucide	@askrjs/askr -> Props	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-lucide	@askrjs/askr/foundations/icon -> IconBase	icon nodes/props follow the public SVG contract	✅
askr-lucide	@askrjs/askr/jsx-runtime -> jsx as createSvgNode	JSX factory/types match the automatic runtime	✅
askr-monaco	@askrjs/askr -> state	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-monaco	@askrjs/askr/foundations/utilities -> Ref	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-monaco	@askrjs/askr/foundations/utilities -> setRef	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-monaco	@askrjs/askr/resources -> task	work is scheduler-owned and cleanup-aware	✅
askr-server	@askrjs/askr/actions -> ActionDescriptor	action descriptors/forms/errors match public request contracts	✅
askr-server	@askrjs/askr/data -> ServerQueryRegistry	query descriptors and server/client registry contracts match declarations	✅
askr-server	@askrjs/askr/router -> ParsedSegment	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> resolveRouteMeta	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> resolveRouteRequest	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> RouteAuthOptions	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> RouteContext	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> RouteManifest	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> RoutePolicy	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> RouteRecord	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> RouteRegistry	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/router -> serializeRouteMeta	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-server	@askrjs/askr/ssr -> renderRouteRequest	render/request results and serialization match public server contracts	✅
askr-server	@askrjs/askr/ssr -> RenderRouteRequestResult	render/request results and serialization match public server contracts	✅
askr-themes	@askrjs/askr -> * as Askr	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-themes	@askrjs/askr -> defineScope	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-themes	@askrjs/askr -> getSignal	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-themes	@askrjs/askr -> readScope	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-themes	@askrjs/askr -> state	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-themes	@askrjs/askr/foundations -> JSXElement	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations -> Slot	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations/state -> controllableState	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations/structures -> cloneElement	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations/structures -> isElement	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations/structures -> JSXElement	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations/utilities -> composeRefs	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations/utilities -> mergeProps	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/foundations/utilities -> Ref	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-themes	@askrjs/askr/jsx-runtime -> jsx	JSX factory/types match the automatic runtime	✅
askr-themes	@askrjs/askr/jsx-runtime -> JSX	JSX factory/types match the automatic runtime	✅
askr-themes	@askrjs/askr/router -> currentRoute	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-themes	@askrjs/askr/router -> Link	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-themes	@askrjs/askr/router -> LinkProps	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
askr-ui	@askrjs/askr -> cspNonce	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr -> defineScope	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr -> For	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr -> getSignal	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr -> Props	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr -> readScope	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr -> registerSSRStyle	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr -> state	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
askr-ui	@askrjs/askr/foundations/interactions -> focusable	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/interactions -> hoverable	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/interactions -> Orientation	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/interactions -> pressable	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/interactions -> rovingFocus	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/interactions -> RovingFocusResult	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/state -> controllableState	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/structures -> Collection	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/structures -> createCollection	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/structures -> createLayer	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/structures -> definePortal	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/structures -> JSXElement	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/structures -> Presence	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/structures -> Slot	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/utilities -> composeRefs	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/utilities -> formatId	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/utilities -> mergeProps	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/foundations/utilities -> Ref	typed refs, structures, and interaction helpers retain documented synchronous semantics	✅
askr-ui	@askrjs/askr/fx -> debounceEvent	work is scheduler-owned and cleanup-aware	✅
askr-ui	@askrjs/askr/resources -> resource	work is scheduler-owned and cleanup-aware	✅
askr-vite	@askrjs/askr/jsx-runtime -> jsx as createElement	JSX factory/types match the automatic runtime	✅
askr-vite	@askrjs/askr/jsx-runtime -> jsxs as createElements	JSX factory/types match the automatic runtime	✅
website	@askrjs/askr -> For	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
website	@askrjs/askr -> Props	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
website	@askrjs/askr -> Show	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
website	@askrjs/askr -> state	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
website	@askrjs/askr/boot -> createSPA	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
website	@askrjs/askr/boot -> hydrateSPA	render-scoped reactive/component APIs retain synchronous ownership semantics	✅
website	@askrjs/askr/resources -> on	work is scheduler-owned and cleanup-aware	✅
website	@askrjs/askr/router -> createRouteRegistry	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> currentRoute	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> fallback	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> group	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> lazy	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> Link	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> onRouteChange	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> route	route descriptors, resolution, navigation, and accessors match documented timing/types	✅
website	@askrjs/askr/router -> RouteSnapshot	route descriptors, resolution, navigation, and accessors match documented timing/types	✅

Every sibling package/website source import was resolved through a declared public subpath. The assumptions match core declarations, docs, and runtime ownership/timing behavior; no undocumented mismatch requiring a new issue was found.

[smiggleworth]

Audit inventory is complete in the issue description. Required concurrency/adversarial coverage landed in #346; the full local gate and hosted Ubuntu/macOS/Windows CI passed. No additional product gap was found.