@makaio/framework 1.0.0-dev-1787670071418 → 1.0.0-dev-1787670559522

package/dist/index-DHnSLGP4.d.mts

@@ -1,268 +0,0 @@
-import { t as CapabilityService } from "./capability-service-BW1-teFU.mjs";
-import { IMakaioBus } from "@makaio/framework/bus";
-import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
-import { CodeExecutionAbortReason, CodeExecutionProviderContext, CodeExecutionRequirements, ICapabilityProvider, ICodeExecutionProvider, MakaioNodeExtension } from "@makaio/framework/contracts";
-import { BaseService } from "@makaio/framework/service-base";
-
-//#region services/core/src/code-execution/code-execution-service.d.ts
-/**
- * Framework router for the `code-execution.execute` subject.
- *
- * Routes one prepared, JSON-safe invocation to exactly one locally registered
- * provider and returns one normalized terminal outcome. The service owns
- * three things and nothing else:
- *
- * - **Selection.** Providers live in the capability registry's
- *   `code-execution` bucket as live objects; this service never keeps a
- *   second registry and re-reads the bucket for every invocation, so
- *   registrations that arrive or disappear between invocations are honored.
- * - **Budget.** One effective signal combines the request budget, the
- *   inherited request deadline, and caller cancellation, and is what the
- *   provider observes.
- * - **Normalization.** Every path — missing provider, malformed
- *   registration, provider throw, non-conforming outcome, timeout,
- *   cancellation — resolves to a schema-valid outcome. The handler does not
- *   reject.
- *
- * There is deliberately **no fallback after admission**: once a provider has
- * been handed the invocation, its failure is normalized, never retried
- * against a second provider. Retrying would run submitted code twice under a
- * different trust level than the one selection admitted.
- */
-declare class CodeExecutionService extends BaseService {
-  private readonly capabilities;
-  /**
-   * @param bus - Bus instance the execute handler is registered on.
-   * @param capabilities - Live capability registry holding the provider bucket.
-   */
-  constructor(bus: IMakaioBus, capabilities: CapabilityService);
-  protected onInit(): void;
-  /**
-   * Validate the delivered payload, then route it.
-   *
-   * The caller-facing input already carries typed JSON fields, but parsing
-   * remains the router's own runtime trust boundary: a handler chain can
-   * replace a payload after the bus validated it, and a subject that executes
-   * submitted code must not hand an unvalidated program to a provider on that
-   * basis.
-   * @param payload - Payload as delivered to this handler.
-   * @param callerSignal - Caller cancellation signal; present only for local dispatch.
-   * @param requestDeadlineEpochMs - Absolute deadline inherited from the request, when any.
-   * @returns Exactly one normalized terminal outcome.
-   */
-  private dispatch;
-  /**
-   * Route one invocation to a single provider and normalize its outcome.
-   *
-   * Budget ownership is established *before* selection, and deliberately so.
-   * An invocation whose caller already went away, or whose inherited deadline
-   * had already passed, was never going to run no matter what the registry
-   * holds; reporting `provider_unavailable` or `invalid_provider` for it would
-   * name a local composition fault as the cause of something the caller
-   * decided. The signal is released on every path, including selection
-   * failure.
-   * @param request - Prepared, JSON-safe invocation to execute.
-   * @param callerSignal - Caller cancellation signal; present only for local dispatch.
-   * @param requestDeadlineEpochMs - Absolute deadline inherited from the request, when any.
-   * @returns Exactly one normalized terminal outcome.
-   */
-  private route;
-  /**
-   * Validate what one admitted provider produced.
-   *
-   * Never rejects: a provider throw and a non-conforming outcome both
-   * normalize here, so the caller's race only ever sees terminal outcomes.
-   * A settlement observed after the effective signal aborted is reported as
-   * that abort rather than as a provider fault — the provider was stopped, it
-   * did not fail.
-   *
-   * INVARIANT: nothing this function holds while suspended may be proportional
-   * to the request. A provider is free to ignore its abort signal and never
-   * settle, in which case the race in {@link route} answers the caller and *this*
-   * frame stays suspended for the life of the process — a suspended async
-   * function retains its parameters, so a `CodeExecutionRequest` parameter would
-   * pin that invocation's whole program and arguments, megabytes apiece, once per
-   * timed-out call. It therefore receives the two bounded strings the post-await
-   * code actually needs instead of the request they came from, and the provider
-   * call itself is started by {@link callProvider} in the caller so that neither
-   * the request nor the selection result is a parameter here. `settlement` is the
-   * provider's own promise: whatever *it* retains is the provider's to answer for,
-   * and is what the abort signal exists to cut short.
-   * @param settlement - Promise the admitted entry point produced, already started.
-   * @param providerId - Identifier selection snapshotted for the admitted provider.
-   * @param invocationId - Correlation identifier, for local diagnostics only.
-   * @param signal - Effective cancellation and deadline ownership for this execution.
-   * @returns The provider's validated outcome, or its normalized failure.
-   */
-  private invoke;
-  /**
-   * Record the detailed cause of a provider fault locally.
-   *
-   * Causes stay here on purpose: the outcome that crosses the bus carries a
-   * bounded summary, so stack traces, paths, and provider-internal error
-   * objects never leave the host that observed them.
-   * @param invocationId - Correlation identifier of the invocation whose provider faulted.
-   * @param providerId - Identifier the selector snapshotted for the faulting provider.
-   * @param summary - What the provider did wrong.
-   * @param cause - Original thrown value or validation error, retained only in the log.
-   */
-  private logDiagnostic;
-}
-//#endregion
-//#region services/core/src/code-execution/package.d.ts
-/** Token for the code-execution routing service. */
-declare const CodeExecutionServiceToken: _$_makaio_contracts0.ExtensionToken<CodeExecutionService>;
-/**
- * Opt-in package that registers the `code-execution.execute` handler.
- *
- * Deliberately **not** part of the framework core package list. The subject's
- * namespace is always registered, so any host can route and validate it, but
- * composing a handler for it means this host is willing to execute submitted
- * code with whatever trust its registered providers declare. That is a
- * composition decision, and it is made by naming this package.
- *
- * The capability registry is a hard dependency rather than a lazy bus lookup:
- * without it there is no provider bucket to select from, and a router that
- * started anyway would answer every invocation with `provider_unavailable`
- * while looking healthy.
- */
-declare const codeExecutionPackage: MakaioNodeExtension<IMakaioBus>;
-//#endregion
-//#region services/core/src/code-execution/execution-signal.d.ts
-/** Inputs from which one effective execution signal is derived. */
-interface EffectiveExecutionSignalOptions {
-  /**
-   * Wall-clock execution budget declared by the request, in milliseconds.
-   *
-   * Must be finite and non-negative; a budget of zero is an already-exhausted
-   * one and settles as a timeout immediately.
-   */
-  readonly timeoutMs: number;
-  /** Absolute deadline inherited from the dispatching request, when it carried one. */
-  readonly requestDeadlineEpochMs?: number;
-  /** Caller cancellation signal; present only for local dispatch. */
-  readonly callerSignal?: AbortSignal;
-}
-/**
- * One execution's effective cancellation and deadline ownership.
- *
- * Combines the request budget, the inherited request deadline, and caller
- * cancellation into the single authoritative signal the provider observes,
- * and records which of them settled it.
- */
-interface EffectiveExecutionSignal {
-  /** Provider-facing context carrying the effective signal and deadline. */
-  readonly context: CodeExecutionProviderContext;
-  /** Reason the signal aborted, or `undefined` while the execution is live. */
-  readonly abortReason: CodeExecutionAbortReason | undefined;
-  /**
-   * Resolves with the abort reason once the signal aborts; never rejects.
-   *
-   * Stays pending forever when the execution settles first, so callers race
-   * it against the provider rather than awaiting it.
-   */
-  readonly aborted: Promise<CodeExecutionAbortReason>;
-  /**
-   * Detach the caller listener and clear the deadline timer.
-   *
-   * Idempotent, and safe to call on every settlement path — including after
-   * the signal already aborted.
-   */
-  release(): void;
-}
-/**
- * Create the effective cancellation and deadline ownership for one execution.
- *
- * The returned signal aborts at the earliest of the request budget, the
- * inherited request deadline, and caller cancellation. Caller cancellation
- * is checked before the deadline so an already-abandoned invocation reports
- * `cancellation` rather than a timeout it never got the chance to exceed.
- *
- * Every listener and timer this installs is removed by
- * {@link EffectiveExecutionSignal.release}, which the caller must invoke on
- * every settlement path.
- *
- * The budget is validated before anything is armed. The bus path already
- * rejects an unusable one through the request schema, but this factory is
- * exported for direct composition too, and there is no signal to hand back for
- * a budget that yields no deadline.
- * @param options - Request budget, inherited deadline, and caller signal.
- * @returns The provider-facing context, the settling reason, and its release.
- * @throws {@link TypeError} When `timeoutMs` is not a finite, non-negative number.
- */
-declare function createEffectiveExecutionSignal(options: EffectiveExecutionSignalOptions): EffectiveExecutionSignal;
-//#endregion
-//#region services/core/src/code-execution/provider-selection.d.ts
-/**
- * Failure codes the selector can produce when no provider is admitted.
- *
- * Both are `failed`-outcome codes, so the router can hand a rejection
- * straight to its failure normalization without re-mapping.
- */
-type CodeExecutionSelectionFailureCode = 'provider_unavailable' | 'invalid_provider';
-/** Selection result admitting exactly one provider for the invocation. */
-interface CodeExecutionProviderSelected {
-  /** Discriminant: a provider was admitted. */
-  readonly admitted: true;
-  /**
-   * The admitted provider's identifier, as read during selection.
-   *
-   * Carried out of the selector rather than re-read from `provider` at the
-   * point of use. Selection reads every field exactly once under containment,
-   * but a registration whose `id` accessor throws — or answers something else —
-   * on a *later* read would otherwise turn a diagnostic or a failure summary
-   * into a rejected bus handler. The identifier a caller reports is therefore
-   * the identifier selection actually admitted.
-   */
-  readonly id: string;
-  /**
-   * The entry point selection validated, carried out of the selector.
-   *
-   * Read once during selection and never read off `provider` again, for the
-   * same reason {@link id} is not: a registration is free to answer a *different*
-   * function on a later read — or to throw — and the callable that runs must be
-   * the callable admission checked. It is invoked with `provider` as its `this`,
-   * so a class-based registration keeps its own binding.
-   */
-  readonly execute: ICodeExecutionProvider['execute'];
-  /** The single provider admitted for this invocation, used as the `this` binding. */
-  readonly provider: ICodeExecutionProvider;
-}
-/** Selection result admitting no provider, carrying the failure classification. */
-interface CodeExecutionProviderRejected {
-  /** Discriminant: no provider was admitted. */
-  readonly admitted: false;
-  /** Failure classification for the normalized outcome. */
-  readonly code: CodeExecutionSelectionFailureCode;
-}
-/** Discriminated result of one selection pass over the live provider bucket. */
-type CodeExecutionProviderSelection = CodeExecutionProviderSelected | CodeExecutionProviderRejected;
-/**
- * Select the single provider that will execute one invocation.
- *
- * Pure over the live bucket: the input array is never reordered or mutated,
- * because it is the capability registry's own storage. Malformed
- * registrations — including ones whose property accessors throw — are
- * excluded from selection rather than invoked, so this function is total: it
- * returns a classification for every bucket instead of throwing at its caller.
- *
- * Every field of every registration is read exactly once, into snapshots;
- * validation, requirement filtering, and ordering then all run on those plain
- * values. The admitted provider's live object leaves this function so it is
- * invoked with its own `this` binding — accompanied by its snapshotted `id` and
- * `execute`, so no caller has to read a field off that live object again, either
- * to describe it or to invoke it.
- *
- * Duplicate snapshot IDs are always `invalid_provider`, before requirement
- * filtering can hide the ambiguity. When no provider is otherwise admitted,
- * `invalid_provider` takes precedence over `provider_unavailable` whenever the
- * bucket held at least one malformed registration. Both are actionable local
- * composition faults, and reporting "no provider available" for either would
- * hide the only signal that something was registered wrongly.
- * @param candidates - Live `code-execution` bucket from the capability registry.
- * @param requirements - Exact-match constraints declared by the request, when any.
- * @returns The admitted provider, or the failure code to normalize.
- */
-declare function selectCodeExecutionProvider(candidates: readonly ICapabilityProvider[], requirements: CodeExecutionRequirements | undefined): CodeExecutionProviderSelection;
-//#endregion
-export { selectCodeExecutionProvider as a, createEffectiveExecutionSignal as c, CodeExecutionService as d, CodeExecutionSelectionFailureCode as i, CodeExecutionServiceToken as l, CodeExecutionProviderSelected as n, EffectiveExecutionSignal as o, CodeExecutionProviderSelection as r, EffectiveExecutionSignalOptions as s, CodeExecutionProviderRejected as t, codeExecutionPackage as u };

package/dist/index-DQ8o3JGi.d.mts

@@ -1,132 +0,0 @@
-import * as _$zod from "zod";
-import { z } from "zod";
-import * as _$_makaio_core0 from "@makaio/framework/core";
-import * as _$zod_v4_core0 from "zod/v4/core";
-
-//#region core/contracts/src/capability/types.d.ts
-/**
- * Base interface all capability providers must implement.
- *
- * Capability providers are registered by extensions to provide
- * platform-specific or service-specific functionality.
- */
-interface ICapabilityProvider {
-  /** Unique identifier for this provider instance */
-  readonly id: string;
-  /** Human-readable name for display in UI */
-  readonly displayName: string;
-  /**
-   * Stable provider identity used for joins across registries.
-   *
-   * Unlike {@link id}, this should remain stable across runtime re-registration.
-   */
-  readonly providerKey?: string;
-  /**
-   * Optional validation method to check provider configuration/credentials.
-   * @returns Validation result with optional error message
-   */
-  validate?(): Promise<{
-    valid: boolean;
-    error?: string;
-  }>;
-}
-/**
- * Interface for capability-based services that can be auto-wired by the runtime.
- *
- * Services implementing this interface can be registered declaratively
- * and the runtime will handle initialization and shutdown automatically.
- */
-interface ICapabilityBasedService {
-  /** The capability ID this service handles */
-  readonly capabilityId: string;
-  /** Initialize the service and register bus handlers */
-  init(): Promise<void>;
-  /** Destroy the service and cleanup handlers. Async teardown is allowed. */
-  destroy(): Promise<void> | void;
-}
-//#endregion
-//#region core/contracts/src/capability/schemas.d.ts
-/**
- * Provider summary for list responses.
- */
-declare const ProviderSummarySchema: z.ZodObject<{
-  id: z.ZodString;
-  displayName: z.ZodString;
-  providerKey: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-/**
- * Validation result for a single provider.
- */
-/**
- * Capability provider registration payload.
- *
- * Note: Provider is typed as unknown at the Zod level because providers
- * are runtime objects with methods that Zod cannot validate.
- * Type safety is enforced via typed registration helpers in service packages.
- */
-declare const ProviderRegistrationSchema: z.ZodObject<{
-  capabilityId: z.ZodString;
-  provider: z.ZodUnknown;
-}, z.core.$strip>;
-/**
- * Capability provider unregistration payload.
- */
-declare const ProviderUnregistrationSchema: z.ZodObject<{
-  capabilityId: z.ZodString;
-  providerId: z.ZodString;
-}, z.core.$strip>;
-/**
- * Capability domain schemas.
- *
- * Subjects for capability-related bus communication.
- * Each key becomes a subject identifier as: `capability.{key}`
- * @example
- * ```typescript
- * // List all push notification providers
- * const result = await bus.request(CapabilitySubjects.listProviders, {
- *   capabilityId: 'push-notification',
- * });
- * ```
- */
-/** Type exports for external use */
-type ProviderSummary = z.infer<typeof ProviderSummarySchema>;
-type ProviderRegistration = z.infer<typeof ProviderRegistrationSchema>;
-type ProviderUnregistration = z.infer<typeof ProviderUnregistrationSchema>;
-//#endregion
-//#region core/contracts/src/capability/namespace.d.ts
-declare const CapabilitySubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"capability", {
-  listProviders: {
-    request: _$zod.ZodObject<{
-      capabilityId: _$zod.ZodString;
-    }, _$zod_v4_core0.$strip>;
-    response: _$zod.ZodObject<{
-      providers: _$zod.ZodArray<_$zod.ZodObject<{
-        id: _$zod.ZodString;
-        displayName: _$zod.ZodString;
-        providerKey: _$zod.ZodOptional<_$zod.ZodString>;
-      }, _$zod_v4_core0.$strip>>;
-    }, _$zod_v4_core0.$strip>;
-  };
-  validate: {
-    request: _$zod.ZodObject<{
-      capabilityId: _$zod.ZodString;
-    }, _$zod_v4_core0.$strip>;
-    response: _$zod.ZodObject<{
-      results: _$zod.ZodArray<_$zod.ZodObject<{
-        id: _$zod.ZodString;
-        valid: _$zod.ZodBoolean;
-        error: _$zod.ZodOptional<_$zod.ZodString>;
-      }, _$zod_v4_core0.$strip>>;
-    }, _$zod_v4_core0.$strip>;
-  };
-  register: _$zod.ZodObject<{
-    capabilityId: _$zod.ZodString;
-    provider: _$zod.ZodUnknown;
-  }, _$zod_v4_core0.$strip>;
-  unregister: _$zod.ZodObject<{
-    capabilityId: _$zod.ZodString;
-    providerId: _$zod.ZodString;
-  }, _$zod_v4_core0.$strip>;
-}>, "capability">;
-//#endregion
-export { ICapabilityBasedService as a, ProviderUnregistration as i, ProviderRegistration as n, ICapabilityProvider as o, ProviderSummary as r, CapabilitySubjects as t };

package/dist/index-DWBkiiXH.d.mts

@@ -1,18 +0,0 @@
-import { t as CapabilityService } from "./capability-service-BW1-teFU.mjs";
-import { IMakaioBus } from "@makaio/framework/bus";
-import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
-import { MakaioNodeExtension } from "@makaio/framework/contracts";
-
-//#region services/core/src/capability/package.d.ts
-/** Token for the capability registry service. */
-declare const CapabilityToken: _$_makaio_contracts0.ExtensionToken<CapabilityService>;
-/**
- * Package that starts the framework capability registry.
- *
- * The token and package live with the service rather than in the aggregate
- * package list so that a domain depending on the capability registry can
- * resolve the token without importing every other framework package.
- */
-declare const capabilityPackage: MakaioNodeExtension<IMakaioBus>;
-//#endregion
-export { capabilityPackage as n, CapabilityToken as t };