@cleocode/cleo 2026.5.4 → 2026.5.6

package/dist/dispatch/adapters/typed.d.ts

@@ -1,362 +0,0 @@
-/**
- * Typed dispatch adapter — single-point compile-time bridge.
- *
- * ## Purpose
- *
- * The canonical {@link DomainHandler} interface accepts `Record<string, unknown>` params
- * on every operation. This forces every handler to hand-cast each field at the call
- * site (`params?.foo as string`). The T910 audit enumerated **579** such casts
- * across 14 domain handlers — latent schema drift with zero compile-time enforcement.
- *
- * This module provides the compile-time "adapter" (Option A in the T910 audit):
- * handlers declare a typed operation record `O extends TypedOpRecord`, and the
- * single `as O[K][0]` cast inside {@link typedDispatch} is the only boundary
- * between the untyped registry and fully-typed per-op params.
- *
- * ## Scope — what this module does and does NOT do
- *
- * - **Does**: Provide a `TypedDomainHandler<O>` interface, a `typedDispatch` helper,
- *   a `defineTypedHandler` builder, and `lafsSuccess` / `lafsError` envelope helpers.
- * - **Does NOT**: Perform runtime validation. A follow-up epic (Wave D Phase 2) will
- *   layer zod schemas on top of this module. Today the cast in `typedDispatch`
- *   trusts the caller — the registry upstream validates that `op` exists in the
- *   handler's operations map, and the contracts in `@cleocode/contracts/src/operations/`
- *   are the typed source of truth for what each op accepts.
- * - **Does NOT**: Replace {@link DomainHandler}. Migrations (T975-T983) wire each
- *   existing handler through this typed layer one domain at a time; the legacy
- *   `DomainHandler` interface remains for back-compat.
- *
- * ## Rationale for the single cast
- *
- * The cast `rawParams as O[K][0]` inside {@link typedDispatch} is the documented
- * "trust boundary". The registry upstream (`registry.ts`) validates the operation
- * name against a known set; the contracts package defines the typed params shape.
- * No other cast is needed because every downstream call site sees the narrowed
- * `O[K][0]` type.
- *
- * @task T974 — Wave D foundation (clean-code SSoT reconciliation epic T962)
- * @see packages/cleo/src/dispatch/domains/diagnostics.ts (gold-standard guard pattern)
- * @see .cleo/agent-outputs/T910-reconciliation/dispatch-cast-audit.md (full audit)
- */
-import type { LafsEnvelope, LafsSuccess } from '@cleocode/contracts';
-/**
- * Infer a `TypedOpRecord` from a Core function registry.
- *
- * Transforms a map of Core functions into a typed operation record by extracting
- * parameter and return types. The inference rule:
- *
- * - **Params**: `Parameters<F>[0]` — the first argument type of the function.
- *   If the function takes no arguments, infers to `Record<string, never>`
- *   (representing a no-op/void-arg operation).
- *
- * - **Result**: `Awaited<ReturnType<F>>` — the resolved type of the function's
- *   return value. If the function returns a `Promise<T>`, unwraps to `T`.
- *   If synchronous, returns the value as-is. This ensures both async and
- *   sync Core functions produce a consistent result type.
- *
- * **Overload Resolution**: TypeScript's `Parameters<F>` and `ReturnType<F>`
- * pick the LAST overload of an overloaded function signature. If a Core function
- * defines multiple overloads, the inferred types correspond to the final overload.
- * This is a known limitation; prefer single-signature Core functions when possible,
- * or manually wire the operation record if overloads have materially different
- * parameter/result shapes.
- *
- * **Escape Hatch**: If `OpsFromCore<C>` inference doesn't fit your needs,
- * you may still hand-write a `TypedOpRecord` — this helper is opt-in and
- * coexists with manual declaration. Both approaches satisfy the same
- * `TypedOpRecord` contract.
- *
- * @typeParam C - A record (often `typeof someModule`) mapping operation names
- *   to Core functions. Each value must be a function matching
- *   `(...args: any[]) => any`.
- *
- * @returns A `TypedOpRecord` (map of operation names to `[Params, Result]`
- *   tuples) suitable for passing to {@link defineTypedHandler}.
- *
- * @example
- * ```ts
- * // Core module defines:
- * export async function nexusList(params: NexusListParams): Promise<NexusListResult> { ... }
- * export async function nexusRegister(params: NexusRegisterParams): Promise<NexusRegisterResult> { ... }
- *
- * // Dispatch adapter creates:
- * import * as nexusCore from '@cleocode/core/nexus';
- *
- * const coreOps = {
- *   'nexus.list':     nexusCore.nexusList,
- *   'nexus.register': nexusCore.nexusRegister,
- * } as const;
- *
- * type NexusOps = OpsFromCore<typeof coreOps>;
- * // Equivalent to:
- * // type NexusOps = {
- * //   'nexus.list':     [NexusListParams, NexusListResult];
- * //   'nexus.register': [NexusRegisterParams, NexusRegisterResult];
- * // };
- *
- * const handler = defineTypedHandler<NexusOps>('nexus', {
- *   'nexus.list': async (params) => { ... },
- *   'nexus.register': async (params) => { ... },
- * });
- * ```
- *
- * **Zero-Argument (Void-Arg) Functions**:
- * ```ts
- * // If Core defines:
- * export async function sessionStatus(): Promise<SessionStatusResult> { ... }
- *
- * // Then:
- * const coreOps = { 'session.status': sessionStatus } as const;
- * type SessionOps = OpsFromCore<typeof coreOps>;
- * // type SessionOps = {
- * //   'session.status': [Record<string, never>, SessionStatusResult];
- * // };
- *
- * // Inside the handler, the params arg is still typed:
- * const handler = defineTypedHandler<SessionOps>('session', {
- *   'session.status': async (_params: Record<string, never>) => {
- *     // _params is empty; safe to ignore.
- *     return lafsSuccess({ ... }, 'session.status');
- *   },
- * });
- * ```
- *
- * @see {@link TypedOpRecord}
- * @see {@link defineTypedHandler}
- * @task T1436 — Wave 0 of T1435 dispatch refactor (eliminate dispatch-vs-contracts drift)
- *
- * **Note on the `any` constraint**: The `(...args: any[]) => any` constraint is REQUIRED
- * for TypeScript to allow generic inference of `Parameters<C[K]>[0]` and `ReturnType<C[K]>`
- * without widening to `unknown`. Tightening this constraint would break the inference.
- * This is a mandatory boundary in the type-system design.
- */
-export type OpsFromCore<C extends Record<string, (...args: any[]) => any>> = {
-    [K in keyof C]: [
-        Parameters<C[K]>[0] extends undefined ? Record<string, never> : Parameters<C[K]>[0],
-        Awaited<ReturnType<C[K]>>
-    ];
-};
-/**
- * Shape of a typed-op record.
- *
- * Each key in the record is an operation name, and each value is a tuple of
- * `[Params, Result]` types. The adapter uses declaration-merging to narrow
- * the handler's operation functions without runtime indirection.
- *
- * @example
- * ```ts
- * import type { SessionStartParams, SessionStartResult } from '@cleocode/contracts';
- *
- * type SessionOps = {
- *   'session.start': [SessionStartParams, SessionStartResult];
- *   'session.status': [Record<string, never>, SessionStatusResult];
- * };
- * ```
- */
-export type TypedOpRecord = Record<string, readonly [unknown, unknown]>;
-/**
- * A fully-typed domain handler.
- *
- * Callers supply an `OPS extends TypedOpRecord` mapping each op name to its
- * typed `[Params, Result]` tuple. Every function in `operations` receives the
- * narrowed `Params` type and returns a `LafsEnvelope<Result>`.
- *
- * @typeParam O - The typed operation record. Each entry is `[Params, Result]`.
- *
- * @example
- * ```ts
- * const handler: TypedDomainHandler<SessionOps> = {
- *   domain: 'session',
- *   operations: {
- *     'session.start': async (params) => lafsSuccess({...}, 'session.start'),
- *     'session.status': async (_params) => lafsSuccess({...}, 'session.status'),
- *   },
- * };
- * ```
- */
-export interface TypedDomainHandler<O extends TypedOpRecord> {
-    /** Canonical domain name (matches the registry key). */
-    readonly domain: string;
-    /**
-     * Per-operation function map. Each op receives its typed params and returns
-     * a `LafsEnvelope<Result>` built with {@link lafsSuccess} or {@link lafsError}.
-     */
-    readonly operations: {
-        readonly [K in keyof O]: (params: O[K][0]) => Promise<LafsEnvelope<unknown>>;
-    };
-}
-/**
- * Dispatch a typed op on a typed handler.
- *
- * Given a `TypedDomainHandler<O>`, dispatches `op` with `rawParams` and returns
- * the handler's `LafsEnvelope<O[K][1]>`. The single `as O[K][0]` cast inside
- * this function is the **documented trust boundary**: the registry upstream
- * guarantees that `op` exists in the handler's operations map and that
- * `rawParams` was constructed from the CLI adapter's validated input.
- *
- * No runtime validation is performed here. Runtime schema validation (zod) is
- * the subject of a separate follow-up epic; inserting it into this function
- * will be a localized change (see the `// Future` comment in the implementation).
- *
- * @typeParam O - The handler's typed operation record.
- * @typeParam K - The specific op key being dispatched.
- * @param handler - The typed handler produced by {@link defineTypedHandler}.
- * @param op - The operation name (must exist in `handler.operations`).
- * @param rawParams - Raw params from the dispatcher middleware. Type-narrowed
- *   to `O[K][0]` by the single boundary cast below.
- * @returns A `LafsEnvelope<O[K][1]>` from the handler's per-op function.
- *
- * @throws Propagates any error thrown by the handler's op function. Callers
- *   that need LAFS-shaped errors should wrap with {@link lafsError} at the
- *   op-fn level; {@link typedDispatch} itself does not catch.
- *
- * @example
- * ```ts
- * const envelope = await typedDispatch(sessionHandler, 'session.start', rawParams);
- * if (envelope.success) console.log(envelope.data); // SessionStartResult
- * ```
- */
-export declare function typedDispatch<O extends TypedOpRecord, K extends keyof O & string>(handler: TypedDomainHandler<O>, op: K, rawParams: unknown): Promise<LafsEnvelope<O[K][1]>>;
-/**
- * Build a {@link TypedDomainHandler} from a domain name and op map.
- *
- * Convenience factory that keeps the domain name and operations record visible
- * at a single call site. Equivalent to writing out the object literal, but
- * makes the generic parameter explicit at the point of construction.
- *
- * @typeParam O - The handler's typed operation record.
- * @param domain - Canonical domain name (matches the registry key).
- * @param operations - Per-op function map produced in user code.
- * @returns A typed handler ready to pass to {@link typedDispatch}.
- *
- * @example
- * ```ts
- * const sessionHandler = defineTypedHandler<SessionOps>('session', {
- *   'session.start': async (params) => lafsSuccess({...}, 'session.start'),
- *   'session.status': async (_params) => lafsSuccess({...}, 'session.status'),
- * });
- * ```
- */
-export declare function defineTypedHandler<O extends TypedOpRecord>(domain: string, operations: TypedDomainHandler<O>['operations']): TypedDomainHandler<O>;
-/**
- * Generate a stable request id for envelope correlation.
- *
- * @internal
- */
-declare function generateRequestId(): string;
-/**
- * Build a LAFS success envelope around `data`.
- *
- * Produces a `LafsSuccess<T>` (the CLI envelope variant from
- * `@cleocode/contracts/src/lafs.ts`). The `operation` argument is accepted
- * for parity with {@link lafsError} but is not persisted on the CLI variant
- * — upstream middleware writes it onto the gateway-enriched envelope
- * (`GatewaySuccess._meta.operation`) when the response crosses the dispatcher
- * boundary.
- *
- * @typeParam T - The data payload type.
- * @param data - The successful result payload.
- * @param _operation - Operation name (accepted for parity; not persisted on
- *   the CLI envelope variant — it is written by the gateway middleware).
- * @returns A `LafsSuccess<T>` envelope.
- *
- * @example
- * ```ts
- * return lafsSuccess({ sessionId: 'ses_…', scope: 'global' }, 'session.start');
- * ```
- */
-export declare function lafsSuccess<T>(data: T, _operation: string, extra?: {
-    page?: import('@cleocode/contracts').LAFSPage;
-}): LafsSuccess<T> & {
-    page?: import('@cleocode/contracts').LAFSPage;
-};
-/**
- * Build a LAFS error envelope.
- *
- * Produces a `LafsError` (the CLI envelope variant from
- * `@cleocode/contracts/src/lafs.ts`). The `operation` argument is accepted
- * for parity with {@link lafsSuccess} but is not persisted on the CLI variant
- * — upstream middleware writes it onto the gateway-enriched envelope
- * (`GatewayError._meta.operation`).
- *
- * @param code - Stable machine-readable error code (e.g. `'E_NOT_FOUND'`).
- * @param message - Human-readable error description.
- * @param _operation - Operation name (accepted for parity; not persisted on
- *   the CLI envelope variant — it is written by the gateway middleware).
- * @param fix - Optional copy-paste fix hint for the caller.
- * @returns A `LafsError` envelope. Typed as `LafsEnvelope<never>` so it
- *   composes with any `LafsEnvelope<T>` return type.
- *
- * @example
- * ```ts
- * return lafsError('E_NOT_FOUND', `task ${id} not found`, 'tasks.show', `cleo find ${id}`);
- * ```
- */
-export declare function lafsError(code: string, message: string, _operation: string, fix?: string): LafsEnvelope<never>;
-/**
- * Wrap a Core engine result into a LAFS envelope.
- *
- * Eliminates the repetitive 8-12 line pattern:
- * ```ts
- * const result = await coreOps.foo(params);
- * if (!result.success) return lafsError(String(result.error?.code ?? 'E_INTERNAL'), ...);
- * return lafsSuccess(result.data ?? fallback, opName);
- * ```
- *
- * Usage:
- * ```ts
- * return wrapCoreResult(await coreOps.foo(params), 'foo', fallback);
- * ```
- *
- * @param result   - Result returned by a Core op wrapper function.
- * @param opName   - Operation name forwarded to {@link lafsError} / {@link lafsSuccess}.
- * @param fallback - Optional default when `result.data` is `null`/`undefined` on success.
- * @returns A `LafsEnvelope` for the operation.
- *
- * @task T1484
- */
-export declare function wrapCoreResult<T = any>(result: {
-    success: boolean;
-    data?: T;
-    error?: {
-        code?: string | number;
-        message?: string;
-    };
-}, opName: string, fallback?: T): LafsEnvelope<T>;
-/**
- * Wrap a conduit `*Impl` call in a standardised try/catch returning a LAFS envelope.
- *
- * All conduit typed-handler ops follow an identical 15-25 line try/catch pattern:
- * ```ts
- * try {
- *   const result = await fooImpl(...params);
- *   if (!result.success) return lafsError(result.error?.code ?? 'E_CONDUIT', ...);
- *   return lafsSuccess(result.data ?? {}, opName);
- * } catch (error) {
- *   return lafsError('E_CONDUIT', error instanceof Error ? error.message : String(error), opName);
- * }
- * ```
- *
- * Usage:
- * ```ts
- * return wrapConduitImpl(() => fooImpl(params.bar, params.baz), 'foo');
- * ```
- *
- * @param fn     - Zero-argument async factory that calls the impl function.
- * @param opName - Operation name forwarded to {@link lafsError} / {@link lafsSuccess}.
- * @returns A `Promise<LafsEnvelope<T>>` for the operation.
- *
- * @task T1484
- */
-export declare function wrapConduitImpl(fn: () => Promise<unknown>, opName: string): Promise<LafsEnvelope<unknown>>;
-/**
- * Internal request-id generator, exposed for deterministic assertions in unit
- * tests. Production callers should never import this directly.
- *
- * @internal
- */
-export declare const __typedInternals: {
-    generateRequestId: typeof generateRequestId;
-};
-export {};
-//# sourceMappingURL=typed.d.ts.map

package/dist/dispatch/adapters/typed.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"typed.d.ts","sourceRoot":"","sources":["../../../src/dispatch/adapters/typed.ts"],"names":[],"mappings":"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"}

package/dist/dispatch/adapters/typed.js

@@ -1,278 +0,0 @@
-/**
- * Typed dispatch adapter — single-point compile-time bridge.
- *
- * ## Purpose
- *
- * The canonical {@link DomainHandler} interface accepts `Record<string, unknown>` params
- * on every operation. This forces every handler to hand-cast each field at the call
- * site (`params?.foo as string`). The T910 audit enumerated **579** such casts
- * across 14 domain handlers — latent schema drift with zero compile-time enforcement.
- *
- * This module provides the compile-time "adapter" (Option A in the T910 audit):
- * handlers declare a typed operation record `O extends TypedOpRecord`, and the
- * single `as O[K][0]` cast inside {@link typedDispatch} is the only boundary
- * between the untyped registry and fully-typed per-op params.
- *
- * ## Scope — what this module does and does NOT do
- *
- * - **Does**: Provide a `TypedDomainHandler<O>` interface, a `typedDispatch` helper,
- *   a `defineTypedHandler` builder, and `lafsSuccess` / `lafsError` envelope helpers.
- * - **Does NOT**: Perform runtime validation. A follow-up epic (Wave D Phase 2) will
- *   layer zod schemas on top of this module. Today the cast in `typedDispatch`
- *   trusts the caller — the registry upstream validates that `op` exists in the
- *   handler's operations map, and the contracts in `@cleocode/contracts/src/operations/`
- *   are the typed source of truth for what each op accepts.
- * - **Does NOT**: Replace {@link DomainHandler}. Migrations (T975-T983) wire each
- *   existing handler through this typed layer one domain at a time; the legacy
- *   `DomainHandler` interface remains for back-compat.
- *
- * ## Rationale for the single cast
- *
- * The cast `rawParams as O[K][0]` inside {@link typedDispatch} is the documented
- * "trust boundary". The registry upstream (`registry.ts`) validates the operation
- * name against a known set; the contracts package defines the typed params shape.
- * No other cast is needed because every downstream call site sees the narrowed
- * `O[K][0]` type.
- *
- * @task T974 — Wave D foundation (clean-code SSoT reconciliation epic T962)
- * @see packages/cleo/src/dispatch/domains/diagnostics.ts (gold-standard guard pattern)
- * @see .cleo/agent-outputs/T910-reconciliation/dispatch-cast-audit.md (full audit)
- */
-import { randomUUID } from 'node:crypto';
-// ---------------------------------------------------------------------------
-// Dispatch helper
-// ---------------------------------------------------------------------------
-/**
- * Dispatch a typed op on a typed handler.
- *
- * Given a `TypedDomainHandler<O>`, dispatches `op` with `rawParams` and returns
- * the handler's `LafsEnvelope<O[K][1]>`. The single `as O[K][0]` cast inside
- * this function is the **documented trust boundary**: the registry upstream
- * guarantees that `op` exists in the handler's operations map and that
- * `rawParams` was constructed from the CLI adapter's validated input.
- *
- * No runtime validation is performed here. Runtime schema validation (zod) is
- * the subject of a separate follow-up epic; inserting it into this function
- * will be a localized change (see the `// Future` comment in the implementation).
- *
- * @typeParam O - The handler's typed operation record.
- * @typeParam K - The specific op key being dispatched.
- * @param handler - The typed handler produced by {@link defineTypedHandler}.
- * @param op - The operation name (must exist in `handler.operations`).
- * @param rawParams - Raw params from the dispatcher middleware. Type-narrowed
- *   to `O[K][0]` by the single boundary cast below.
- * @returns A `LafsEnvelope<O[K][1]>` from the handler's per-op function.
- *
- * @throws Propagates any error thrown by the handler's op function. Callers
- *   that need LAFS-shaped errors should wrap with {@link lafsError} at the
- *   op-fn level; {@link typedDispatch} itself does not catch.
- *
- * @example
- * ```ts
- * const envelope = await typedDispatch(sessionHandler, 'session.start', rawParams);
- * if (envelope.success) console.log(envelope.data); // SessionStartResult
- * ```
- */
-export async function typedDispatch(handler, op, rawParams) {
-    // ------------------------------------------------------------------------
-    // Trust boundary (single-point cast).
-    //
-    // `rawParams` is `unknown` at the registry boundary. The CLI adapter
-    // (`packages/cleo/src/dispatch/adapters/cli.ts`) has already unpacked the
-    // wire format via `params-resolver`, and the registry's `resolveOperation`
-    // guarantees that `op` exists in `handler.operations`. This cast is the
-    // ONLY point in the typed adapter where `unknown` becomes a concrete params
-    // type; every downstream call site sees the narrowed `O[K][0]`.
-    //
-    // Future (Wave D Phase 2, separate epic): insert zod parsing here to gate
-    // drift at runtime as well as at compile time. The shape would be:
-    //
-    //   const schema = OpSchemas[handler.domain][op];
-    //   const parsed = schema.safeParse(rawParams);
-    //   if (!parsed.success) {
-    //     return lafsError('E_VALIDATION', parsed.error.message, `${handler.domain}.${op}`);
-    //   }
-    //   return handler.operations[op](parsed.data);
-    //
-    // See packages/contracts/src/operations/*.ts for the typed Params contracts
-    // that would back these schemas.
-    // ------------------------------------------------------------------------
-    return handler.operations[op](rawParams);
-}
-// ---------------------------------------------------------------------------
-// Builder
-// ---------------------------------------------------------------------------
-/**
- * Build a {@link TypedDomainHandler} from a domain name and op map.
- *
- * Convenience factory that keeps the domain name and operations record visible
- * at a single call site. Equivalent to writing out the object literal, but
- * makes the generic parameter explicit at the point of construction.
- *
- * @typeParam O - The handler's typed operation record.
- * @param domain - Canonical domain name (matches the registry key).
- * @param operations - Per-op function map produced in user code.
- * @returns A typed handler ready to pass to {@link typedDispatch}.
- *
- * @example
- * ```ts
- * const sessionHandler = defineTypedHandler<SessionOps>('session', {
- *   'session.start': async (params) => lafsSuccess({...}, 'session.start'),
- *   'session.status': async (_params) => lafsSuccess({...}, 'session.status'),
- * });
- * ```
- */
-export function defineTypedHandler(domain, operations) {
-    return { domain, operations };
-}
-// ---------------------------------------------------------------------------
-// LAFS envelope helpers
-// ---------------------------------------------------------------------------
-/**
- * Generate a stable request id for envelope correlation.
- *
- * @internal
- */
-function generateRequestId() {
-    return randomUUID();
-}
-/**
- * Build a LAFS success envelope around `data`.
- *
- * Produces a `LafsSuccess<T>` (the CLI envelope variant from
- * `@cleocode/contracts/src/lafs.ts`). The `operation` argument is accepted
- * for parity with {@link lafsError} but is not persisted on the CLI variant
- * — upstream middleware writes it onto the gateway-enriched envelope
- * (`GatewaySuccess._meta.operation`) when the response crosses the dispatcher
- * boundary.
- *
- * @typeParam T - The data payload type.
- * @param data - The successful result payload.
- * @param _operation - Operation name (accepted for parity; not persisted on
- *   the CLI envelope variant — it is written by the gateway middleware).
- * @returns A `LafsSuccess<T>` envelope.
- *
- * @example
- * ```ts
- * return lafsSuccess({ sessionId: 'ses_…', scope: 'global' }, 'session.start');
- * ```
- */
-export function lafsSuccess(data, _operation, extra) {
-    return {
-        success: true,
-        data,
-        ...(extra?.page ? { page: extra.page } : {}),
-    };
-}
-/**
- * Build a LAFS error envelope.
- *
- * Produces a `LafsError` (the CLI envelope variant from
- * `@cleocode/contracts/src/lafs.ts`). The `operation` argument is accepted
- * for parity with {@link lafsSuccess} but is not persisted on the CLI variant
- * — upstream middleware writes it onto the gateway-enriched envelope
- * (`GatewayError._meta.operation`).
- *
- * @param code - Stable machine-readable error code (e.g. `'E_NOT_FOUND'`).
- * @param message - Human-readable error description.
- * @param _operation - Operation name (accepted for parity; not persisted on
- *   the CLI envelope variant — it is written by the gateway middleware).
- * @param fix - Optional copy-paste fix hint for the caller.
- * @returns A `LafsError` envelope. Typed as `LafsEnvelope<never>` so it
- *   composes with any `LafsEnvelope<T>` return type.
- *
- * @example
- * ```ts
- * return lafsError('E_NOT_FOUND', `task ${id} not found`, 'tasks.show', `cleo find ${id}`);
- * ```
- */
-export function lafsError(code, message, _operation, fix) {
-    const error = { code, message };
-    if (fix !== undefined)
-        error.fix = fix;
-    return {
-        success: false,
-        error,
-    };
-}
-// ---------------------------------------------------------------------------
-// Thin-dispatch helpers (T1484 · ADR-057 D3)
-// ---------------------------------------------------------------------------
-/**
- * Wrap a Core engine result into a LAFS envelope.
- *
- * Eliminates the repetitive 8-12 line pattern:
- * ```ts
- * const result = await coreOps.foo(params);
- * if (!result.success) return lafsError(String(result.error?.code ?? 'E_INTERNAL'), ...);
- * return lafsSuccess(result.data ?? fallback, opName);
- * ```
- *
- * Usage:
- * ```ts
- * return wrapCoreResult(await coreOps.foo(params), 'foo', fallback);
- * ```
- *
- * @param result   - Result returned by a Core op wrapper function.
- * @param opName   - Operation name forwarded to {@link lafsError} / {@link lafsSuccess}.
- * @param fallback - Optional default when `result.data` is `null`/`undefined` on success.
- * @returns A `LafsEnvelope` for the operation.
- *
- * @task T1484
- */
-// biome-ignore lint/suspicious/noExplicitAny: fallback must accept any data shape
-export function wrapCoreResult(result, opName, fallback) {
-    if (!result.success) {
-        return lafsError(String(result.error?.code ?? 'E_INTERNAL'), result.error?.message ?? 'Unknown error', opName);
-    }
-    return lafsSuccess((result.data ?? fallback), opName);
-}
-/**
- * Wrap a conduit `*Impl` call in a standardised try/catch returning a LAFS envelope.
- *
- * All conduit typed-handler ops follow an identical 15-25 line try/catch pattern:
- * ```ts
- * try {
- *   const result = await fooImpl(...params);
- *   if (!result.success) return lafsError(result.error?.code ?? 'E_CONDUIT', ...);
- *   return lafsSuccess(result.data ?? {}, opName);
- * } catch (error) {
- *   return lafsError('E_CONDUIT', error instanceof Error ? error.message : String(error), opName);
- * }
- * ```
- *
- * Usage:
- * ```ts
- * return wrapConduitImpl(() => fooImpl(params.bar, params.baz), 'foo');
- * ```
- *
- * @param fn     - Zero-argument async factory that calls the impl function.
- * @param opName - Operation name forwarded to {@link lafsError} / {@link lafsSuccess}.
- * @returns A `Promise<LafsEnvelope<T>>` for the operation.
- *
- * @task T1484
- */
-export async function wrapConduitImpl(fn, opName) {
-    try {
-        // biome-ignore lint/suspicious/noExplicitAny: conduit impl types are heterogeneous
-        const result = (await fn());
-        if (!result.success) {
-            return lafsError(String(result.error?.code ?? 'E_CONDUIT'), result.error?.message ?? 'Unknown error', opName);
-        }
-        return lafsSuccess(result.data ?? {}, opName);
-    }
-    catch (error) {
-        return lafsError('E_CONDUIT', error instanceof Error ? error.message : String(error), opName);
-    }
-}
-// ---------------------------------------------------------------------------
-// Internal exports for testing
-// ---------------------------------------------------------------------------
-/**
- * Internal request-id generator, exposed for deterministic assertions in unit
- * tests. Production callers should never import this directly.
- *
- * @internal
- */
-export const __typedInternals = { generateRequestId };
-//# sourceMappingURL=typed.js.map

package/dist/dispatch/adapters/typed.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"typed.js","sourceRoot":"","sources":["../../../src/dispatch/adapters/typed.ts"],"names":[],"mappings":"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"}