@makaio/framework 1.0.0-dev-1785409369816 → 1.0.0-dev-1786014320559

package/dist/index-BFhJe-Sb.d.mts

@@ -0,0 +1,302 @@
+import { n as NodeExtensionContext$1, t as ExtensionContext$1 } from "./extension-context-CqfddWXs.mjs";
+import { z } from "zod";
+import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
+
+//#region core/contracts/src/reaction/schemas.d.ts
+/**
+ * Serializable descriptor advertising a contributed Reaction.
+ *
+ * A descriptor is discovery metadata only: it carries the Reaction identity,
+ * a human-readable description, and a derived JSON Schema representation of
+ * the parameter shape. It can never synthesize or transport the Reaction's
+ * executable handler — runtime truth is always the live
+ * {@link ReactionDefinition} contributed by the owning extension.
+ *
+ * The `kind` field is the canonical Reaction identity in the form
+ * `<extension-name>.<reaction-name>`. Namespace ownership is enforced by the
+ * Reaction registry at contribution time, not by this schema.
+ */
+declare const ReactionDescriptorSchema$1: z.ZodObject<{
+  kind: z.ZodString;
+  description: z.ZodString;
+  parameterSchema: z.ZodType<Record<string, _$_makaio_contracts0.JsonValue>, Record<string, _$_makaio_contracts0.JsonValue>, z.core.$ZodTypeInternals<Record<string, _$_makaio_contracts0.JsonValue>, Record<string, _$_makaio_contracts0.JsonValue>>>;
+}, z.core.$strip>;
+/** Serializable descriptor advertising a contributed Reaction. */
+type ReactionDescriptor$1 = z.infer<typeof ReactionDescriptorSchema$1>;
+/**
+ * Serializable normalized outcome of a single Reaction invocation.
+ *
+ * A handler that resolves normally maps to `{ success: true }`; a handler
+ * that throws maps to `{ success: false }` with a plain error message.
+ * Cancellation is cooperative: a handler that resolves despite an abort
+ * still yields `{ success: true }` — only dispatches that are already
+ * aborted or already past their deadline before handler entry are
+ * guaranteed failure outcomes. The outcome intentionally carries no retry,
+ * ordering, or durability semantics — every host dispatch is an independent
+ * invocation.
+ */
+declare const ReactionOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  success: z.ZodLiteral<true>;
+}, z.core.$strip>, z.ZodObject<{
+  success: z.ZodLiteral<false>;
+  error: z.ZodObject<{
+    message: z.ZodString;
+  }, z.core.$strip>;
+}, z.core.$strip>], "success">;
+/** Serializable normalized outcome of a single Reaction invocation. */
+type ReactionOutcome$1 = z.infer<typeof ReactionOutcomeSchema>;
+//#endregion
+//#region core/contracts/src/reaction/execution.d.ts
+declare const reactionRuleRefBrand: unique symbol;
+/**
+ * Identifier for a single Reaction invocation.
+ *
+ * Minted by the dispatching runtime for every host dispatch. Invocations are
+ * independent: there is no ordering, deduplication, or exactly-once promise
+ * attached to this identifier — it exists for logging, outcome correlation,
+ * and cancellation bookkeeping only.
+ */
+type ReactionInvocationId = string;
+/**
+ * Opaque host-supplied reference to whatever caused a Reaction dispatch.
+ *
+ * Rule systems are consumer-owned: a host that evaluates rules attaches its
+ * own rule reference here so it can recognize the invocation in logs and
+ * outcomes. The framework never interprets this value — it is a branded
+ * marker type that deliberately imports no domain definition or persistence
+ * model. Hosts mint refs via {@link createReactionRuleRef}.
+ */
+interface ReactionRuleRef$1 {
+  /** Opaque brand preventing accidental structural construction. */
+  readonly [reactionRuleRefBrand]: true;
+}
+/**
+ * Brands a host-owned reference as a {@link ReactionRuleRef}.
+ *
+ * The host keeps full access to its own reference value via the intersection
+ * return type; framework code only ever sees the opaque brand and passes the
+ * value through untouched. References may be primitives or objects.
+ * @typeParam TRef - Host-owned reference value being branded.
+ * @param ref - Host-owned reference value to brand.
+ * @returns The same value typed as `TRef & ReactionRuleRef`.
+ */
+declare function createReactionRuleRef<TRef>(ref: TRef): TRef & ReactionRuleRef$1;
+/**
+ * Frozen execution envelope supplied to a Reaction handler.
+ *
+ * The runtime captures and freezes the envelope's top-level fields at dispatch
+ * time. The handler therefore observes the same `eventKind`, event payload,
+ * and host-composed context that the host used to evaluate its rule and
+ * resolve parameters. The framework does not compose or detach domain values:
+ * `eventPayload`, `hostContext`, and `ruleRef` are opaque host-owned
+ * references passed through unchanged. They may be shared and mutable. A host
+ * that requires deeper isolation must detach those values before invocation.
+ *
+ * Every host dispatch has a separate envelope and independent cancellation
+ * and deadline controls. Host-owned values are not thereby isolated or
+ * ordered across invocations.
+ */
+interface ReactionExecutionContext {
+  /** Runtime-minted identifier for this invocation. */
+  readonly invocationId: ReactionInvocationId;
+  /**
+   * Opaque host-supplied reference to the rule that caused this dispatch.
+   *
+   * `undefined` when the host dispatched without a rule system — rule systems
+   * are consumer-owned and not required for dispatch.
+   */
+  readonly ruleRef: ReactionRuleRef$1 | undefined;
+  /** Event kind string the host evaluated when deciding to dispatch. */
+  readonly eventKind: string;
+  /**
+   * Event payload the host evaluated, supplied verbatim.
+   *
+   * Opaque to the framework; it remains a host-owned reference and handlers
+   * narrow it with host-specific knowledge.
+   */
+  readonly eventPayload: unknown;
+  /**
+   * Host-composed context available during rule evaluation and parameter
+   * resolution, supplied verbatim.
+   *
+   * Opaque to the framework; it remains a host-owned reference and handlers
+   * narrow it with host-specific knowledge.
+   */
+  readonly hostContext: unknown;
+  /**
+   * Bus correlation identifier propagated from the triggering message, when
+   * one exists.
+   */
+  readonly correlationId: string | undefined;
+  /**
+   * Runtime-controlled cancellation signal for this invocation.
+   *
+   * Handlers should pass this to long-running operations so they cancel
+   * promptly when the runtime aborts the invocation. Cancellation is
+   * cooperative: a handler that ignores the signal and resolves still
+   * yields a success outcome.
+   */
+  readonly signal: AbortSignal;
+  /**
+   * Absolute deadline hint for this invocation as epoch milliseconds, or
+   * `undefined` when the host imposed no deadline.
+   *
+   * The dispatcher guarantees only that an invocation which is already
+   * aborted or already past this deadline never enters handler code; it does
+   * not promise an exact-instant abort. Handlers may consult the deadline
+   * proactively to budget their own work, but must treat {@link signal} as
+   * the sole source of truth for cancellation.
+   */
+  readonly deadlineEpochMs: number | undefined;
+}
+//#endregion
+//#region core/contracts/src/reaction/definition.d.ts
+/**
+ * Trusted asynchronous Reaction handler.
+ *
+ * Receives parameters that were already validated against the Reaction's live
+ * `parameterSchema` by the dispatching runtime, together with the frozen
+ * {@link ReactionExecutionContext} envelope for this invocation.
+ * @typeParam TParams - Validated parameter shape for this Reaction.
+ * @param parameters - Schema-validated, read-only invocation parameters.
+ * @param context - Frozen execution envelope for this invocation.
+ * @returns Resolves when the Reaction's side-effects are complete.
+ */
+type ReactionHandler<TParams extends Record<string, unknown> = Record<string, unknown>> = (parameters: Readonly<TParams>, context: ReactionExecutionContext) => Promise<void>;
+/**
+ * Executable Reaction contributed by an extension.
+ *
+ * This is the type-erased shape stored on contribution surfaces and consumed
+ * by the Reaction registry; typed authoring happens through
+ * {@link defineReaction}, which erases the parameter type after wiring the
+ * live schema and handler together. The live `parameterSchema` and `handler`
+ * are function-carrying runtime values and must never be treated as
+ * serializable descriptor data — `toDescriptor()` produces the only
+ * serializable representation.
+ */
+interface ReactionDefinition$1 {
+  /**
+   * Canonical Reaction kind: `<extension-name>.<reaction-name>`.
+   *
+   * Namespace ownership (the `<extension-name>.` prefix matching the
+   * contributing extension) is enforced by the Reaction registry at
+   * contribution time.
+   */
+  readonly kind: string;
+  /** Human-readable description of what this Reaction does when invoked. */
+  readonly description: string;
+  /**
+   * Live Zod schema for the Reaction's invocation parameters.
+   *
+   * The dispatching runtime validates raw parameters against this schema
+   * before invoking {@link handler}.
+   */
+  readonly parameterSchema: z.ZodType<Record<string, unknown>>;
+  /**
+   * Trusted executable handler for this Reaction.
+   *
+   * Invariant: callers MUST pass parameters that were validated with
+   * {@link parameterSchema} — the typed inner handler installed by
+   * {@link defineReaction} narrows them under that contract.
+   */
+  readonly handler: ReactionHandler;
+  /**
+   * Produces the serializable {@link ReactionDescriptor} for this Reaction.
+   * @returns Discovery metadata with a derived JSON Schema parameter shape;
+   *   never includes the live schema or handler. Each call returns a detached
+   *   snapshot owned by the caller; mutating it cannot affect later discovery.
+   */
+  readonly toDescriptor: () => ReactionDescriptor$1;
+}
+/**
+ * Options for {@link defineReaction}.
+ * @typeParam TParams - Parameter shape validated by `parameterSchema`.
+ */
+interface DefineReactionOptions<TParams extends Record<string, unknown>> {
+  /**
+   * Canonical Reaction kind: `<extension-name>.<reaction-name>`.
+   * The Reaction registry enforces the extension-name prefix at contribution time.
+   */
+  readonly kind: string;
+  /** Human-readable description of what this Reaction does when invoked. */
+  readonly description: string;
+  /** Live Zod schema for the Reaction's invocation parameters. */
+  readonly parameterSchema: z.ZodType<TParams>;
+  /** Typed handler receiving already-validated read-only parameters. */
+  readonly handler: ReactionHandler<TParams>;
+}
+/**
+ * Creates an executable Reaction definition with a live parameter schema, a
+ * typed handler, and a serializable descriptor.
+ *
+ * The returned definition is type-erased for storage on contribution
+ * surfaces; the typed `handler` from the options keeps its parameter type
+ * internally and is invoked under the invariant that the dispatching runtime
+ * validated the parameters with `parameterSchema` first. Definition creation
+ * derives serializable discovery metadata — the live schema and handler are
+ * never serialized.
+ * @typeParam TParams - Parameter shape validated by `parameterSchema`.
+ * @param options - Reaction identity, description, live parameter schema, and
+ *   typed handler.
+ * @returns A type-erased {@link ReactionDefinition} ready for contribution.
+ * @throws Error when the Reaction identity or input parameter schema cannot
+ *   form a serializable {@link ReactionDescriptorSchema}, enforced fail-fast
+ *   at definition time so `toDescriptor()` can never fail discovery.
+ * @example
+ * ```ts
+ * export const notifyReaction = defineReaction({
+ *   kind: 'my-extension.notify-owner',
+ *   description: 'Notifies the owning user about a host-selected event.',
+ *   parameterSchema: z.object({ channel: z.string(), message: z.string() }),
+ *   handler: async (parameters, context) => {
+ *     await sendNotification(parameters.channel, parameters.message, {
+ *       signal: context.signal,
+ *     });
+ *   },
+ * });
+ * ```
+ */
+declare function defineReaction<TParams extends Record<string, unknown>>(options: DefineReactionOptions<TParams>): ReactionDefinition$1;
+//#endregion
+//#region core/contracts/src/reaction/contribution.d.ts
+/**
+ * Context supplied to the `createReactions` factory of an
+ * {@link ExtensionReactionsContribution}.
+ *
+ * This is a semantically named alias over the applicable host
+ * {@link ExtensionContext} — an API-evolution seam, not a second dependency
+ * container. Reaction factories receive the same per-extension runtime
+ * context as other executable contribution factories; the alias exists so
+ * the Reaction surface can grow reaction-specific context fields later
+ * without changing every factory signature.
+ * @typeParam THostContext - Concrete context shape supplied by the host
+ *   runtime. Defaults to {@link NodeExtensionContext} because the current
+ *   framework hosts are Node-based.
+ */
+type ReactionContributionContext<THostContext extends ExtensionContext$1 = NodeExtensionContext$1> = THostContext;
+/**
+ * Executable Reactions contribution surface declared by an extension.
+ *
+ * The runtime calls `createReactions(ctx)` during extension activation and
+ * atomically registers the returned definitions as that extension's complete
+ * Reaction batch.
+ * Definitions carry live Zod parameter schemas and trusted handlers — they
+ * are runtime values, never serializable descriptor data.
+ * @typeParam THostContext - Concrete context shape supplied by the host
+ *   runtime. Defaults to {@link NodeExtensionContext} because the current
+ *   framework hosts are Node-based.
+ */
+interface ExtensionReactionsContribution<THostContext extends ExtensionContext$1 = NodeExtensionContext$1> {
+  /**
+   * Factory that produces the Reaction definitions for this extension.
+   *
+   * Called during extension activation. Each result is the extension's
+   * complete Reaction batch and atomically replaces its prior batch. Returning
+   * a `Promise` allows async resource acquisition (e.g. lazy loading).
+   * @param ctx - Per-extension runtime context supplied by the host.
+   * @returns Reaction definitions or a promise that resolves to them.
+   */
+  readonly createReactions: (ctx: ReactionContributionContext<THostContext>) => readonly ReactionDefinition$1[] | Promise<readonly ReactionDefinition$1[]>;
+}
+//#endregion
+export { ReactionHandler as a, ReactionInvocationId as c, ReactionDescriptor$1 as d, ReactionDescriptorSchema$1 as f, ReactionDefinition$1 as i, ReactionRuleRef$1 as l, ReactionOutcomeSchema as m, ReactionContributionContext as n, defineReaction as o, ReactionOutcome$1 as p, DefineReactionOptions as r, ReactionExecutionContext as s, ExtensionReactionsContribution as t, createReactionRuleRef as u };

package/dist/{index-EjsSBQXy2.d.mts → index-BSQ30wYP.d.mts}

@@ -1,4 +1,4 @@
-import { c as AdapterRuntimeSnapshotErrorCode } from "./schemas-BsVYZviy.mjs";
+import { c as AdapterRuntimeSnapshotErrorCode } from "./schemas-DZH9lpxs.mjs";
 import { IMakaioBus } from "@makaio/framework/bus";
 import { ProviderContext, ResolvedProviderContext } from "@makaio/framework/contracts";
 

package/dist/{index-DlsHL9Jg.d.mts → index-BiAYXjgM.d.mts}

@@ -1,4 +1,4 @@
-import { H as ClientDefinition, U as ClientDefinitionInput } from "./hook-responses-Dh1PWXqJ.mjs";
+import { D as ClientDefinitionInput, E as ClientDefinition } from "./hook-responses-CQZIv3L3.mjs";
 import * as _$zod from "zod";
 import { z } from "zod";
 import * as _$_makaio_core0 from "@makaio/framework/core";
@@ -17,8 +17,8 @@ declare const ClientExecutionContextSchema: z.ZodObject<{
   env: z.ZodRecord<z.ZodString, z.ZodString>;
   configDir: z.ZodNullable<z.ZodString>;
   source: z.ZodEnum<{
-    global: "global";
     managed: "managed";
+    global: "global";
   }>;
   version: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
@@ -39,8 +39,8 @@ declare const ClientResolveBinarySchema: {
     sessionId: z.ZodOptional<z.ZodString>;
     projectDir: z.ZodOptional<z.ZodString>;
     preferSource: z.ZodOptional<z.ZodEnum<{
-      global: "global";
       managed: "managed";
+      global: "global";
     }>>;
     harnessId: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
@@ -49,8 +49,8 @@ declare const ClientResolveBinarySchema: {
     env: z.ZodRecord<z.ZodString, z.ZodString>;
     configDir: z.ZodNullable<z.ZodString>;
     source: z.ZodEnum<{
-      global: "global";
       managed: "managed";
+      global: "global";
     }>;
     version: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>;
@@ -506,11 +506,11 @@ declare const ClientSchemas: {
     cwd: z.ZodOptional<z.ZodString>;
     machineId: z.ZodOptional<z.ZodString>;
     startMode: z.ZodOptional<z.ZodEnum<{
-      fork: "fork";
-      resume: "resume";
       fresh: "fresh";
-      compact: "compact";
+      resume: "resume";
+      fork: "fork";
       clear: "clear";
+      compact: "compact";
     }>>;
     parentAdapterSessionId: z.ZodOptional<z.ZodString>;
   }, z.core.$strip>;
@@ -698,8 +698,8 @@ declare const ClientSchemas: {
       sessionId: z.ZodOptional<z.ZodString>;
       projectDir: z.ZodOptional<z.ZodString>;
       preferSource: z.ZodOptional<z.ZodEnum<{
-        global: "global";
         managed: "managed";
+        global: "global";
       }>>;
       harnessId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
@@ -708,8 +708,8 @@ declare const ClientSchemas: {
       env: z.ZodRecord<z.ZodString, z.ZodString>;
       configDir: z.ZodNullable<z.ZodString>;
       source: z.ZodEnum<{
-        global: "global";
         managed: "managed";
+        global: "global";
       }>;
       version: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>;
@@ -1486,11 +1486,11 @@ type ClientSessionObservedBase = z.infer<typeof ClientSessionObservedBaseSchema>
 declare const CLIENT_SESSION_START_MODES: readonly ["fresh", "fork", "resume", "clear", "compact"];
 /** Zod schema for the client-reported session start mode. */
 declare const ClientSessionStartModeSchema: z.ZodEnum<{
-  fork: "fork";
-  resume: "resume";
   fresh: "fresh";
-  compact: "compact";
+  resume: "resume";
+  fork: "fork";
   clear: "clear";
+  compact: "compact";
 }>;
 /** Client-reported session start mode discriminator. */
 type ClientSessionStartMode = z.infer<typeof ClientSessionStartModeSchema>;
@@ -1505,11 +1505,11 @@ declare const ClientSessionStartedSchema: z.ZodObject<{
   cwd: z.ZodOptional<z.ZodString>;
   machineId: z.ZodOptional<z.ZodString>;
   startMode: z.ZodOptional<z.ZodEnum<{
-    fork: "fork";
-    resume: "resume";
     fresh: "fresh";
-    compact: "compact";
+    resume: "resume";
+    fork: "fork";
     clear: "clear";
+    compact: "compact";
   }>>;
   parentAdapterSessionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -2076,11 +2076,11 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
     cwd: _$zod.ZodOptional<_$zod.ZodString>;
     machineId: _$zod.ZodOptional<_$zod.ZodString>;
     startMode: _$zod.ZodOptional<_$zod.ZodEnum<{
-      fork: "fork";
-      resume: "resume";
       fresh: "fresh";
-      compact: "compact";
+      resume: "resume";
+      fork: "fork";
       clear: "clear";
+      compact: "compact";
     }>>;
     parentAdapterSessionId: _$zod.ZodOptional<_$zod.ZodString>;
   }, _$zod_v4_core0.$strip>;
@@ -2268,8 +2268,8 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
       sessionId: _$zod.ZodOptional<_$zod.ZodString>;
       projectDir: _$zod.ZodOptional<_$zod.ZodString>;
       preferSource: _$zod.ZodOptional<_$zod.ZodEnum<{
-        global: "global";
         managed: "managed";
+        global: "global";
       }>>;
       harnessId: _$zod.ZodOptional<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;
@@ -2278,8 +2278,8 @@ declare const ClientNamespace: _$_makaio_core0.BusNamespaceDefinition<"client",
       env: _$zod.ZodRecord<_$zod.ZodString, _$zod.ZodString>;
       configDir: _$zod.ZodNullable<_$zod.ZodString>;
       source: _$zod.ZodEnum<{
-        global: "global";
         managed: "managed";
+        global: "global";
       }>;
       version: _$zod.ZodNullable<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;
@@ -2716,11 +2716,11 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
     cwd: _$zod.ZodOptional<_$zod.ZodString>;
     machineId: _$zod.ZodOptional<_$zod.ZodString>;
     startMode: _$zod.ZodOptional<_$zod.ZodEnum<{
-      fork: "fork";
-      resume: "resume";
       fresh: "fresh";
-      compact: "compact";
+      resume: "resume";
+      fork: "fork";
       clear: "clear";
+      compact: "compact";
     }>>;
     parentAdapterSessionId: _$zod.ZodOptional<_$zod.ZodString>;
   }, _$zod_v4_core0.$strip>;
@@ -2908,8 +2908,8 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
       sessionId: _$zod.ZodOptional<_$zod.ZodString>;
       projectDir: _$zod.ZodOptional<_$zod.ZodString>;
       preferSource: _$zod.ZodOptional<_$zod.ZodEnum<{
-        global: "global";
         managed: "managed";
+        global: "global";
       }>>;
       harnessId: _$zod.ZodOptional<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;
@@ -2918,8 +2918,8 @@ declare const ClientSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSu
       env: _$zod.ZodRecord<_$zod.ZodString, _$zod.ZodString>;
       configDir: _$zod.ZodNullable<_$zod.ZodString>;
       source: _$zod.ZodEnum<{
-        global: "global";
         managed: "managed";
+        global: "global";
       }>;
       version: _$zod.ZodNullable<_$zod.ZodString>;
     }, _$zod_v4_core0.$strip>;