march-hare 0.8.0 → 0.9.0

package/dist/{hooks → actions}/index.d.ts

@@ -1,6 +1,5 @@
 import { Data } from './types';
-import { Model, Props, Actions, UseActions, Context as ContextHandle } from '../types/index';
-export { With } from './utils';
+import { Model, Props, Actions, UseActions } from '../types/index';
 /**
  * A hook for managing state with actions.
  *
@@ -43,41 +42,5 @@ export { With } from './utils';
  * >(initialModel, () => ({ query: props.query }));
  * ```
  */
-export declare function useActions<_M extends void = void, A extends Actions | void = void, D extends Props = Props>(getData?: Data<D>): UseActions<void, A, D>;
+export declare function useActions<M extends void = void, A extends Actions | void = void, D extends Props = Props>(getData?: Data<D>): UseActions<M, A, D>;
 export declare function useActions<M extends Model, A extends Actions | void = void, D extends Props = Props>(initialModel: M, getData?: Data<D>): UseActions<M, A, D>;
-/**
- * Returns a stable, typed controller handle up-front &mdash; before a
- * model is declared via `context.useActions(...)`. Use this when an
- * external imperative library (form, animation, third-party SDK) needs a
- * dispatch callback at construction time, while the value that library
- * returns must flow back into the controller's data callback.
- *
- * The handle exposes `dispatch(action, payload?)` and a `useView(...)`
- * method that materialises the component-local model and reactive data
- * &mdash; the M and D pair of `useContext<M, AC, D>` &mdash; and
- * returns the `[model, actions, data]` tuple with `useAction`, `dispatch`,
- * `inspect`, and `stream` attached. The first invocation of
- * `context.actions.dispatch(...)` must come from an event handler &mdash; not
- * synchronously during render &mdash; because the underlying dispatch
- * target is wired up when `context.useActions(...)` runs in the same
- * render pass.
- *
- * @template M The model type representing the component's state.
- * @template AC The actions class containing action definitions.
- * @template D The data type for reactive external values.
- *
- * @example
- * ```ts
- * const context = useContext<Model, typeof Actions, Data>();
- *
- * const form = useForm({
- *   onSubmit: () => void context.actions.dispatch(Actions.Submit),
- * });
- *
- * const actions = context.useActions(
- *   { user: user() },
- *   () => ({ form }),
- * );
- * ```
- */
-export declare function useContext<M extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>(): ContextHandle<M, AC, D>;

package/dist/{hooks → actions}/utils.d.ts

@@ -63,45 +63,6 @@ export declare function useLifecycles({ unicast, broadcast, dispatchers, scope,
  * @returns A memoized data proxy of the object.
  */
 export declare function useData<P extends Props>(props: P): P;
-/**
- * Handler factories that wire an action directly to a model field.
- *
- * - {@link With.Update} assigns the dispatched payload to `model[key]`.
- * - {@link With.Invert} flips a boolean field on `model[key]`.
- *
- * Both are typed so the call site fails to compile when `key` is missing or
- * has an incompatible type.
- *
- * @example
- * ```ts
- * import { With } from "march-hare";
- *
- * type Model = { name: string; sidebar: boolean };
- *
- * class Actions {
- *   static SetName = Action<string>("SetName");
- *   static ToggleSidebar = Action("ToggleSidebar");
- * }
- *
- * actions.useAction(Actions.SetName, With.Update("name"));
- * actions.useAction(Actions.ToggleSidebar, With.Invert("sidebar"));
- * ```
- */
-export declare const With: {
-    /**
-     * Returns a handler that assigns the action payload to `model[key]`.
-     *
-     * Type-checks at the call site: the payload type must be assignable to
-     * the model property's type, and the key must exist on the model.
-     */
-    Update<K extends string>(key: K): <M extends Model, A extends Actions | void, D extends Props, P extends K extends keyof M ? M[K] : never>(context: HandlerContext<M, A, D>, payload: P) => void;
-    /**
-     * Returns a handler that inverts a boolean field on the model.
-     *
-     * Type-checks at the call site: `model[key]` must be a boolean.
-     */
-    Invert<K extends string>(key: K): <M extends Model & Record<K, boolean>, A extends Actions | void, D extends Props>(context: HandlerContext<M, A, D>) => void;
-};
 /**
  * Scans a handler registry for a lifecycle action of the given type.
  *

package/dist/app/index.d.ts

@@ -0,0 +1,112 @@
+import { Env } from '../boundary/components/env/index';
+import { Actions, Model, Props } from '../types/index';
+import { Scope } from '../scope/index';
+import { AppContextHandle, AppResource } from './types';
+import * as React from "react";
+export type { AppArgs, AppContextHandle, AppFetcher, AppResource, } from './types';
+/**
+ * Returned from {@link App}. Bundles the Boundary, hooks, and Resource
+ * factory bound to a single typed Env shape `S`.
+ */
+export type App<S extends object> = {
+    /**
+     * Boundary component for this App. Wraps the subtree with the initial
+     * `env` value passed to {@link App}.
+     */
+    readonly Boundary: React.FC<{
+        children: React.ReactNode;
+    }>;
+    /**
+     * Hook returning a stable `Context` handle. The handle's
+     * `context.useActions(initialModel?, getData?)` materialises the
+     * component's `[model, actions, data]` tuple. Every handler's
+     * `context.env` is typed as `S`.
+     */
+    readonly useContext: <M extends Model | void = void, AC extends Actions | void = void, D extends Props = Props>() => AppContextHandle<M, AC, D, S>;
+    /**
+     * Read-only Proxy over the per-Boundary Env, typed as `S`. Reads use
+     * dot notation (`env.session`) and always reflect the latest value
+     * across `await` boundaries. Writes flow through
+     * `context.actions.produce(({ env }) => { ... })`.
+     */
+    readonly useEnv: () => Readonly<S>;
+    /**
+     * `Resource` factory bound to this App's Env. Same shape as the
+     * top-level `Resource`: call directly for an in-memory cache, or use
+     * `app.Resource.Cachable(cache, fetcher)` for persistence.
+     */
+    readonly Resource: AppResource<S>;
+    /**
+     * Opens a typed multicast scope. The generic `MulticastActions` declares
+     * the `Distribution.Multicast` action class (or union of classes)
+     * whose dispatches are routed through this scope &mdash; the
+     * returned handle mirrors the App surface but widens
+     * `useContext().actions.dispatch` to accept actions from `MulticastActions`
+     * on top of the local `AC` class.
+     *
+     * Render `<scope.Boundary>` to open the scope at runtime; nesting
+     * multiple boundaries from different `app.Scope()` calls is fine,
+     * each runs as an independent emitter shadowed for its subtree.
+     *
+     * The Scope handle deliberately does NOT expose a further `Scope`
+     * method &mdash; the multicast surface must be declared at the
+     * `app.Scope<MulticastActions>()` call site so the type union is explicit.
+     */
+    readonly Scope: <MulticastActions>() => Scope<S, MulticastActions>;
+};
+/**
+ * Creates an `App` &mdash; the entrypoint for a typed Env shape `S`,
+ * inferred from `config.env`. `App<S>` exposes `Boundary`, hooks, and
+ * a `Resource` factory all wired against the same shape.
+ *
+ * Each `<app.Boundary>` instance owns its own Env, so different `App`s
+ * can coexist in the same tree with completely independent shapes.
+ *
+ * @example
+ * ```tsx
+ * import { App } from "march-hare";
+ *
+ * type Session = { accessToken: string };
+ *
+ * export const app = App({
+ *   env: {
+ *     session: null as Session | null,
+ *     operating: "idle" as "idle" | "signing-out",
+ *   },
+ * });
+ *
+ * // Root render.
+ * <app.Boundary>
+ *   <Root />
+ * </app.Boundary>;
+ *
+ * // In a feature's actions.ts:
+ * export function useAuthActions() {
+ *   const context = app.useContext<void, typeof Actions>();
+ *   const actions = context.useActions();
+ *
+ *   actions.useAction(Actions.SignOut, async (context) => {
+ *     context.actions.produce(({ env }) => {
+ *       env.session = null;
+ *     });
+ *   });
+ *
+ *   return actions;
+ * }
+ *
+ * // In resources.ts:
+ * export const user = app.Resource<User>((context) =>
+ *   ky
+ *     .get("/api/user", {
+ *       headers: context.env.session
+ *         ? { Authorization: `Bearer ${context.env.session.accessToken}` }
+ *         : {},
+ *       signal: context.controller.signal,
+ *     })
+ *     .json<User>(),
+ * );
+ * ```
+ */
+export declare function App<S extends object = Env>(config?: {
+    env: S;
+}): App<S>;

package/dist/app/types.d.ts

@@ -0,0 +1,49 @@
+import { Args, ResourceHandle } from '../resource/types';
+import { Cache } from '../cache/index';
+import { Actions, Context, Model, Props, UseActions } from '../types/index';
+import { Data } from '../actions/types';
+/**
+ * Args object passed to an `app.Resource` fetcher. Same shape as the
+ * base `Resource` fetcher's args but with `env` typed as `S`.
+ */
+export type AppArgs<S, P extends object = Record<never, never>> = Omit<Args<P>, "env"> & {
+    readonly env: Readonly<S>;
+};
+/**
+ * Fetcher signature for an `app.Resource` declaration. The fetcher's
+ * `context.env` is typed against the App's inferred Env shape `S`.
+ */
+export type AppFetcher<S, T, P extends object = Record<never, never>> = (context: AppArgs<S, P>) => Promise<T>;
+/**
+ * `app.Resource(fetcher)` &mdash; in-memory cache, no persistence.
+ * `app.Resource.Cachable(cache, fetcher)` &mdash; persistent cache wired
+ * to the supplied `Cache` adapter. Both forms type `context.env` as
+ * the App's Env shape.
+ */
+export type AppResource<S> = {
+    <T, P extends object = Record<never, never>>(fetcher: AppFetcher<S, T, P>): ResourceHandle<T, P>;
+    readonly Cachable: <T, P extends object = Record<never, never>>(cache: Cache, fetcher: AppFetcher<S, T, P>) => ResourceHandle<T, P>;
+};
+/**
+ * Phantom marker so consumers of the App's hooks see `env: S` typing
+ * at the type-system level; at runtime the value is the same proxy as
+ * the loose `Env` type.
+ *
+ * @internal
+ */
+type EnvView<S> = {
+    readonly __appEnv?: S;
+};
+type AppActionsResult<M, AC, D, S> = UseActions<M extends Model | void ? M : void, AC extends Actions | void ? AC : void, D extends Props ? D : Props> & EnvView<S>;
+type AppUseActions<M, AC, D, S> = M extends void ? (getData?: Data<D & Props>) => AppActionsResult<M, AC, D, S> : (initialModel: M, getData?: Data<D & Props>) => AppActionsResult<M, AC, D, S>;
+/**
+ * `Context` handle returned by `app.useContext()`. Mirrors the base
+ * {@link Context} but with the Env-typed slots overridden to `S`.
+ */
+export type AppContextHandle<M, AC, D, S> = {
+    readonly actions: {
+        dispatch: Context<M extends Model | void ? M : void, AC extends Actions | void ? AC : void, D extends Props ? D : Props>["actions"]["dispatch"];
+    };
+    readonly useActions: AppUseActions<M, AC, D, S>;
+};
+export {};

package/dist/boundary/components/broadcast/utils.d.ts

@@ -6,7 +6,7 @@ import * as React from "react";
  * When a broadcast or multicast action is dispatched, the payload is
  * stored so that late-mounting components can replay it via
  * {@link useLifecycles} and handlers can read it via
- * `context.actions.resolution()`.
+ * `context.actions.final()`.
  */
 export declare class BroadcastEmitter extends EventEmitter {
     private cache;

package/dist/boundary/components/env/index.d.ts

@@ -0,0 +1,26 @@
+import { Props } from './types';
+import * as React from "react";
+export { useEnv } from './utils';
+/**
+ * Loose runtime shape for the per-`<Boundary>` Env. Each {@link App}
+ * narrows this to its own typed env via `App<S>({ env })`; the
+ * loose type exists so the framework's internal plumbing
+ * (`<Boundary>`, `useEnv`, handler `context.env`, Resource
+ * fetcher `context.env`) does not need to be parametric over S.
+ *
+ * Consumers should declare their Env shape inline via `App({ env })`
+ * &mdash; the inferred `S` is what flows through `app.useContext`,
+ * `app.useEnv`, and `app.Resource`. Module augmentation of `Env`
+ * is no longer required.
+ */
+export type Env = Record<string, unknown>;
+/**
+ * Provides a per-Boundary {@link Env} value to every component inside
+ * the boundary. Usually wired in via the `<Boundary env={initial}>`
+ * prop rather than used directly.
+ *
+ * The Env is **not** reactive. Mutating it does not trigger a
+ * re-render. Drive view state through the model; use the Env for
+ * cross-handler coordination.
+ */
+export declare function Env({ initial, children }: Props): React.ReactNode;

package/dist/boundary/components/env/types.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { Env } from './index';
+export type { Env } from './index';
+/**
+ * Props for the Env provider component. Accepts the initial Env
+ * value that satisfies the augmented {@link Env} interface.
+ */
+export type Props = {
+    initial: Env;
+    children: ReactNode;
+};

package/dist/boundary/components/env/utils.d.ts

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+import { Env } from './index';
+import * as React from "react";
+/**
+ * React context exposing the per-Boundary Env ref. The ref itself is
+ * stable across renders — readers grab `.current` at call time.
+ *
+ * @internal
+ */
+export declare const Context: React.Context<React.RefObject<Env>>;
+/**
+ * Hook that returns a read-only handle to the per-Boundary {@link Env}.
+ * Reads use plain dot notation (`env.session`) and always reflect the
+ * latest value, even after `await` boundaries &mdash; the handle is a
+ * `Proxy` that delegates property access to the live ref.
+ *
+ * Writes are not exposed here. Mutate the Env inside an action handler
+ * via `context.actions.produce(({ model, env }) => { env.x = ... })`
+ * &mdash; the same Immer-style recipe used for the model. Mutations do
+ * **not** trigger a re-render; drive view state through the model.
+ *
+ * Prefer `app.useEnv()` from an {@link App} instance &mdash; the App
+ * factory infers the Env's shape from `app.env` and types every
+ * read/write against it. The bare `useEnv()` exists for non-App
+ * call sites and returns the loose {@link Env} record type.
+ */
+export declare function useEnv(): Env;
+/**
+ * Internal accessor for the per-Boundary Env ref &mdash; used by the
+ * Resource layer to pass a fresh snapshot to each fetcher invocation
+ * and by the action layer to write through `context.actions.produce`.
+ * Not exported from the library.
+ *
+ * @internal
+ */
+export declare function useEnvRef(): RefObject<Env>;

package/dist/boundary/components/scope/index.d.ts

@@ -1,40 +1,2 @@
-import { MulticastPayload } from '../../../types/index';
-import { ComponentType, ReactNode } from 'react';
-export { useScope, getScope } from './utils';
+export { Context, useScope, getScope } from './utils';
 export type { ScopeEntry, ScopeContext } from './types';
-/**
- * Higher-order component that opens a multicast scope keyed by the supplied
- * multicast action. Components rendered inside the wrapped tree (and any
- * descendants) participate in the scope: every dispatch of `action` reaches
- * every subscriber inside this boundary.
- *
- * Each multicast action defines its own scope — pass the same action you
- * declared with `Distribution.Multicast` to both `withScope` and
- * `actions.dispatch`.
- *
- * Multicast caches the most recent dispatched value per scope so late-mounted
- * components can read it via `context.actions.resolution()`.
- *
- * @param action - The multicast action that opens this scope.
- * @param Component - The component to wrap.
- * @returns A component that renders the original inside a fresh scope boundary.
- *
- * @example
- * ```tsx
- * export class Scope {
- *   static Mood = Action<Mood>("Mood", Distribution.Multicast);
- * }
- *
- * function Mood() {
- *   return (
- *     <>
- *       <Happy />
- *       <Sad />
- *     </>
- *   );
- * }
- *
- * export default withScope(Scope.Mood, Mood);
- * ```
- */
-export declare function withScope<P extends object, T = unknown>(action: MulticastPayload<T>, Component: ComponentType<P>): (props: P) => ReactNode;

package/dist/boundary/components/scope/types.d.ts

@@ -1,20 +1,24 @@
 import { BroadcastEmitter } from '../broadcast/utils';
-import { ActionId } from '../tasks/types';
 /**
- * Represents a single scope in the ancestor chain. The scope key is the
- * action id of the multicast action that opens the scope; each multicast
- * action defines its own scope.
+ * Runtime entry for a single multicast scope opened by an
+ * `<app.Scope().Boundary>`. The `id` uniquely identifies this scope
+ * instance; the `emitter` carries every multicast event dispatched
+ * inside the boundary, keyed internally by the action's symbol.
+ *
+ * Nested boundaries shadow outer ones via React context.
+ *
+ * @internal
  */
 export type ScopeEntry = {
-    /** The action id that opened this scope */
-    action: ActionId;
-    /** BroadcastEmitter for multicast events within this scope (caches last payload per event) */
-    emitter: BroadcastEmitter;
+    readonly id: symbol;
+    readonly emitter: BroadcastEmitter;
 };
 /**
- * The scope context is a flattened map of ancestor scopes keyed by the
- * multicast action that opened each scope. Each `withScope` merges its entry
- * with the parent's map, building up a complete lookup table for O(1)
- * retrieval. null indicates no scope ancestor.
+ * The scope context. `null` when no `<app.Scope().Boundary>` exists in
+ * the ancestor chain; otherwise the nearest entry &mdash; React context
+ * shadowing makes nested boundaries override outer ones for the
+ * subtree.
+ *
+ * @internal
  */
-export type ScopeContext = Map<ActionId, ScopeEntry> | null;
+export type ScopeContext = ScopeEntry | null;

package/dist/boundary/components/scope/utils.d.ts

@@ -1,19 +1,23 @@
 import { ScopeContext, ScopeEntry } from './types';
-import { ActionId } from '../tasks/types';
 import * as React from "react";
 /**
- * React context for the scope chain.
- * Starts as null (no scopes).
+ * React context for the nearest multicast scope. `null` at the root.
+ *
+ * @internal
  */
 export declare const Context: React.Context<ScopeContext>;
 /**
- * Hook to access the scope context from the nearest ancestor.
+ * Hook that returns the nearest multicast scope entry. `null` when
+ * the caller is not rendered inside any `<app.Scope().Boundary>`.
  *
- * @returns The scope context chain, or null if not inside any scope.
+ * @internal
  */
 export declare function useScope(): ScopeContext;
 /**
- * Looks up the scope opened by the given multicast action.
- * O(1) lookup from the flattened scope map.
+ * Pass-through accessor. Kept for the dispatch/subscribe sites that
+ * previously needed an action-keyed lookup; now the scope is a single
+ * entry (or `null`), so this returns it as-is.
+ *
+ * @internal
  */
-export declare function getScope(context: ScopeContext, action: ActionId): ScopeEntry | null;
+export declare function getScope(context: ScopeContext): ScopeEntry | null;

package/dist/boundary/components/sharing/index.d.ts

@@ -0,0 +1,43 @@
+import { PendingCall } from '../../../resource/index';
+import * as React from "react";
+/**
+ * Per-`<Boundary>` registry for `.coalesce(token)` sharing. Outer map
+ * keys on the `PendingCall.run` function identity (stable per Resource
+ * via the `build()` closure); inner map keys on
+ * `${paramsKey}|${coalesceKey(token)}`. While an entry exists every
+ * caller awaiting `.coalesce(token)` for the same Resource + params +
+ * token receives the same promise.
+ *
+ * Lifted into React context so each `<app.Boundary>` owns its own
+ * registry &mdash; two `App` instances in the same tree cannot collide
+ * on a shared token like `.coalesce("k")`.
+ *
+ * @internal
+ */
+export type Sharing = WeakMap<PendingCall["run"], Map<string, Promise<unknown>>>;
+/**
+ * React context exposing the per-Boundary sharing registry. The
+ * fallback is a fresh `WeakMap` used when `useSharing()` is read
+ * outside any `<Boundary>` &mdash; calls work but never share with any
+ * other component.
+ *
+ * @internal
+ */
+export declare const Context: React.Context<Sharing>;
+/**
+ * Wraps children with a Boundary-scoped sharing registry for
+ * `.coalesce(token)`. Rendered as part of {@link Boundary}; not
+ * exposed standalone.
+ *
+ * @internal
+ */
+export declare function SharingProvider({ children, }: {
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * Hook returning the per-Boundary sharing registry. Used by the
+ * `.coalesce(token)` chainable inside `useActions`.
+ *
+ * @internal
+ */
+export declare function useSharing(): Sharing;

package/dist/boundary/index.d.ts

@@ -1,21 +1,21 @@
 import { Props } from './types';
 import * as React from "react";
 /**
- * Creates a unified context boundary for all March Hare features.
- * Wraps children with Broadcaster, Store, and Tasks providers.
+ * Low-level boundary primitive. Wraps children with the Broadcaster,
+ * Env, and Tasks providers required by every March Hare hook.
  *
- * Use this at the root of your application or to create isolated context
- * boundaries for libraries that need their own March Hare context.
- *
- * Pass the `store` prop with the initial Store value (session, locale,
- * feature flags, etc.) — the shape is determined by module
- * augmentation on the library's `Store` interface.
+ * Most applications should reach for {@link App} instead —
+ * `App<S>({ env })` returns a typed `app.Boundary` along with
+ * matching `useContext` / `useEnv` / `Resource` factories that all
+ * close over the App's inferred env shape `S`. The bare `Boundary`
+ * is exposed for advanced or library-internal use where the loose
+ * Env record type is sufficient.
  *
  * @example
  * ```tsx
- * <Boundary store={{ session: null, locale: "en-GB" }}>
+ * <Boundary env={{ session: null, locale: "en-GB" }}>
  *   <App />
  * </Boundary>
  * ```
  */
-export declare function Boundary({ store, children }: Props): React.ReactNode;
+export declare function Boundary({ env, children }: Props): React.ReactNode;

package/dist/boundary/types.d.ts

@@ -1,22 +1,12 @@
-import { Store } from './components/store/types';
+import { Env } from './components/env/types';
 import type * as React from "react";
 export type Props = {
     /**
-     * Initial value of the per-Boundary {@link Store}. The shape is
-     * derived from module augmentation — declare the keys your
-     * application needs once via:
-     *
-     * ```ts
-     * declare module "march-hare" {
-     *   interface Store {
-     *     session: Session | null;
-     *     locale: string;
-     *   }
-     * }
-     * ```
-     *
-     * Optional only when the augmented Store has no required keys.
+     * Initial value of the per-Boundary {@link Env}. Prefer `App({ env })`
+     * — it infers the Env shape and threads it through `app.useContext`,
+     * `app.useEnv`, and `app.Resource`. Pass `env` directly here only for
+     * advanced cases where the loose {@link Env} record type is sufficient.
      */
-    store?: Store;
+    env?: Env;
     children: React.ReactNode;
 };

package/dist/cache/index.d.ts

@@ -28,11 +28,11 @@ export type { Adapter, Encoded } from './types';
  *   clear: () => localStorage.clear(),
  * });
  *
- * // Wired into a Resource — successful runs write through automatically.
- * export const cat = Resource(
- *   async ({ controller }) => fetchCat(controller.signal),
+ * // Wire it into a Resource — successful runs write through automatically.
+ * export const cat = Resource({
  *   cache,
- * );
+ *   fetch: (context) => fetchCat(context.controller.signal),
+ * });
  * ```
  */
 export type Cache = {

package/dist/coalesce/index.d.ts

@@ -0,0 +1,57 @@
+import { Coalesce } from '../resource/types';
+/**
+ * Sentinel token used when `.coalesce()` is called with no explicit
+ * argument. Every untokened caller for the same `(Resource, params)`
+ * slot collapses onto this single key, so multiple callers chaining
+ * `.coalesce()` share one in-flight fetch.
+ *
+ * The symbol description follows the `march-hare.{category}/{name}`
+ * convention used by the rest of the library's internal symbols.
+ *
+ * @internal
+ */
+export declare const token: unique symbol;
+/**
+ * Builds the per-call dedupe key for `.coalesce(token)`.
+ *
+ * The full registry key (constructed at the call site) is
+ * `${JSON.stringify(params)}|${coalesceKey(token)}`; this function is
+ * responsible only for the trailing token segment. Every supported
+ * `Coalesce` primitive (`string`, `number`, `bigint`, `boolean`,
+ * `symbol`) is prefixed with a single-character type tag so that
+ * structurally identical values from different types stay distinct
+ * — e.g. the string `"5"` does not collide with the number `5`,
+ * and `Symbol("X")` does not collide with the string `"X"`.
+ *
+ * Symbols are keyed by their `description` (falling back to
+ * `String(value)` for description-less symbols) so two `Symbol("X")`
+ * instances declared in separate modules still hash to the same key.
+ * That is intentional: the public contract is "same description →
+ * same coalesce group", which keeps the API friendly for the common
+ * enum-token pattern at call sites.
+ *
+ * Any unrecognised value falls through to the object branch and is
+ * keyed by its JSON shape; `Coalesce` is constrained to primitives at
+ * the type level, so this branch is reachable only from `unknown`
+ * coercion in tests.
+ *
+ * @internal
+ */
+export declare function coalesceKey(value: Coalesce): string;
+/**
+ * Wraps `promise` so that aborting `signal` rejects the returned
+ * promise with `signal.reason`, even when `promise` itself never
+ * settles. The original promise is left alone — the underlying
+ * work continues (other awaiters keep their grip) and only this
+ * caller's view of it is severed.
+ *
+ * Used by the `.coalesce(token)` chainable: the shared in-flight fetch
+ * runs on a detached `AbortController` so one caller's abort does not
+ * cancel work the others are still waiting on, while each caller's own
+ * `context.task.controller` still aborts its personal await via this
+ * wrapper. The `{ once: true }` listener and the cleanup on settle keep
+ * the wrapper free of leaks across long-lived signals.
+ *
+ * @internal
+ */
+export declare function withAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T>;