@cleocode/cleo 2026.4.158 → 2026.5.0

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

@@ -0,0 +1,362 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,278 @@
+/**
+ * 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

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