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

package/dist/index-B0VO0rAl.d.mts

@@ -0,0 +1,302 @@
+import { n as NodeExtensionContext$1, t as ExtensionContext$1 } from "./extension-context-QmFuHdq5.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-gUhidukN.d.mts → index-B0yMCJW8.d.mts}

@@ -1,5 +1,6 @@
+import { r as ExecutionTarget } from "./schemas-B50oWBuj.mjs";
 import { IMakaioBus } from "@makaio/framework/bus";
-import { IMakaioSession, MakaioSessionAgent, Message, MessageInput, MessageOutcome, ResponseSchemaDescriptor, SessionContext, TurnInitiator } from "@makaio/framework/contracts";
+import { IMakaioSession, MakaioSessionAgent, Message, MessageInput, MessageOutcome, ReasoningLevelMap, ResponseSchemaDescriptor, SessionContext, SessionOwnershipRecoveryGuard, TurnInitiator } from "@makaio/framework/contracts";
 
 //#region services/core/src/session/entities/turn.d.ts
 /**
@@ -541,6 +542,217 @@ declare class SessionTurnManager {
   private findTurnForCompletion;
 }
 //#endregion
+//#region services/core/src/session/utils/resolution.d.ts
+/**
+ * Resolve adapterName → adapterId for bus routing.
+ * Queries the adapters table for a local enabled instance.
+ * @param bus - Bus instance
+ * @param adapterName - Adapter type name
+ * @param machineId - Optional machine ID for deterministic local resolution
+ * @returns Canonical adapter ID for bus routing
+ * @throws if no enabled instance found for this adapterName
+ */
+declare function resolveAdapterId(bus: IMakaioBus, adapterName: string, machineId?: string): Promise<string>;
+/**
+ * The adapter instance an ownership act runs against, together with the machine
+ * whose namespace it acts in.
+ *
+ * **One value, because it is one key.** The ownership key is
+ * `(machine, adapter instance, provider session)` and an instance ID is derived
+ * from `(machineId, adapterName)`, so an act that took its instance from one
+ * source and its machine from another files itself under a pair nobody else
+ * computes. Carrying both halves in one object is what makes "instance and
+ * namespace come from one identity" structural rather than a rule every call
+ * site has to remember.
+ *
+ * `machineId` is absent for exactly one caller shape — one that named no machine
+ * and is therefore not acting for any: it gets the unscoped answer, the
+ * authority acts under its own composed identity, and there are no two
+ * identities to mix.
+ */
+interface OwnedAdapterInstance {
+  /** Live adapter instance every act of the attempt addresses. */
+  readonly adapterId: string;
+  /** Machine whose namespace those acts are filed under, or `undefined` when the caller named none. */
+  readonly machineId?: string;
+  /** Exact runtime owner, absent only before a connector-dispatchable target is proved. */
+  readonly ownerInstanceId?: string;
+}
+/**
+ * An owned instance whose machine is named.
+ *
+ * The shape a path that performs a **keyed** ownership act needs, stated as a
+ * type so the requirement is checked rather than remembered: a keyed act files
+ * itself under `(machine, instance, provider session)`, so a path that can reach
+ * one may not hold an instance whose machine is unnamed. Wave 3 left exactly
+ * that hole — a fresh lead start reserves keyless, which hides the machine's
+ * absence, and then settles on the provider session the connector confirms,
+ * which does not.
+ */
+type MachineScopedAdapterInstance = OwnedAdapterInstance & {
+  readonly machineId: string;
+  readonly ownerInstanceId: string;
+};
+/** What a caller knows about the instance it wants, before it is resolved. */
+interface OwnedAdapterInstanceTarget {
+  /** Adapter type name the instance belongs to. */
+  readonly adapterName: string;
+  /**
+   * Instance the caller named itself, when it named one.
+   *
+   * Only usable together with {@link OwnedAdapterInstanceTarget.machineId}: the
+   * derivation is one-way, so a named instance whose machine is unnamed is half
+   * an identity, and half an identity is worse than none.
+   */
+  readonly adapterId?: string;
+  /**
+   * Machine every act of this attempt names, or `undefined` when the caller
+   * names none.
+   */
+  readonly machineId?: string;
+  /**
+   * Instance this agent was last known to live on, offered as a fallback for the
+   * unscoped form only.
+   *
+   * A persisted instance goes stale across a runtime restart or a failover, so
+   * it is never preferred — but for a caller that names no machine it beats
+   * failing a whole recovery because a registry lookup was momentarily
+   * unavailable, and it cannot mix two identities because there is only one.
+   */
+  readonly storedAdapterId?: string;
+}
+/**
+ * Prove that an explicitly selected adapter instance is currently live on the
+ * exact machine the selection names.
+ *
+ * The proof is announcement-backed rather than hash-backed: hosts may provide
+ * opaque adapter IDs, and a deterministic-looking value is not evidence that a
+ * runtime has initialized it.
+ * @param bus - Bus the live-identity request is issued on.
+ * @param target - Complete identity the caller intends to dispatch to.
+ * @returns The dispatchable instance, or `undefined` when it has no matching live announcement.
+ */
+declare function resolveAnnouncedAdapterInstance(bus: IMakaioBus, target: Required<Pick<OwnedAdapterInstanceTarget, 'adapterId' | 'adapterName' | 'machineId'>>): Promise<MachineScopedAdapterInstance | undefined>;
+/**
+ * Resolve the instance an attempt addresses **and** the machine it acts for, or
+ * answer that this runtime may not act at all.
+ *
+ * One seam for a rule that was split in three: a fresh resolution for every act
+ * (a persisted instance goes stale across a restart or a failover), the machine
+ * carried alongside it, and the refusal when the two cannot be produced
+ * together. Reserving against one instance and dispatching to another reserves
+ * in a namespace the dispatch never uses, and reserving under machine X while
+ * dispatching to machine R's instance builds a key no other actor computes — it
+ * collides with nothing, so it protects nothing, and the runtime that really
+ * owns that instance claims the same provider session beside it.
+ *
+ * **The three answers, and why each is the honest one:**
+ *
+ * - **A named instance with its machine** is returned only after the live
+ *   identity registry confirms the exact triple it announced. The selection
+ *   schema proves the request is complete; the announcement proves the target
+ *   currently exists, including when its host supplied an opaque ID.
+ * - **A named instance without a machine** is `undefined`. This is the handler-side
+ *   half of the schema's refinement, and it is needed as well as the schema:
+ *   the test bus does not validate, and defaulting to this runtime's own identity
+ *   here is precisely the silent mis-key the refinement exists to prevent.
+ * - **No named instance** derives one. With a machine named, a derivation that
+ *   cannot answer is `undefined` — the stored instance may not stand in, because
+ *   the machine it belongs to cannot be recovered from it. With no machine named,
+ *   the attempt is unscoped in every act, so the stored instance is an honest
+ *   fallback.
+ *
+ * `undefined` means *this runtime may not act for that machine*, never *this
+ * failed*. Translating it is the caller's job, because only the caller knows
+ * what its own refusal looks like: a send defers the agent, a restart reports a
+ * non-native recovery, a start refuses to dispatch.
+ * @param bus - Bus the lookup is issued on.
+ * @param target - What the caller knows about the instance and the machine it acts for.
+ * @returns Both halves of the key, or `undefined` when this runtime may not act for that machine.
+ */
+declare function resolveOwnedAdapterInstance(bus: IMakaioBus, target: OwnedAdapterInstanceTarget): Promise<OwnedAdapterInstance | undefined>;
+/**
+ * Resolve supported reasoning levels for a model from provider definitions.
+ *
+ * Looks up the provider config by ID, finds the provider definition it belongs to,
+ * then finds the model's `supportedReasoningLevels` in the provider's `availableModels`
+ * catalog.
+ * @param bus - Bus instance for RPC calls
+ * @param providerConfigId - Canonical provider config ID (ProviderConfigRecord.id)
+ * @param model - Model identifier to look up in the provider's catalog
+ * @returns Object with `supportedReasoningLevels` when found, or `undefined` when not resolvable
+ */
+declare function resolveModelCapabilities(bus: IMakaioBus, providerConfigId: string | undefined, model: string | undefined): Promise<{
+  supportedReasoningLevels?: ReasoningLevelMap;
+} | undefined>;
+/**
+ * Resolves the effective execution target for a session.
+ * Priority: explicit executionTargetId → system default (local).
+ * @param bus - Makaio bus instance
+ * @param params - Resolution parameters from session context
+ * @returns Resolved execution target
+ */
+declare function resolveExecutionTarget(bus: IMakaioBus, params: {
+  executionTargetId?: string;
+}): Promise<ExecutionTarget>;
+//#endregion
+//#region services/core/src/session/handlers/session-start-error.d.ts
+/**
+ * Why a reserved start could not be completed, as a value the caller can branch
+ * on.
+ *
+ * Every member names a *modeled* outcome of the ownership seam, not a bug: a
+ * start that reaches a live connector can still be refused ownership of what
+ * that connector is talking to, and the caller has to be told which of those
+ * happened rather than being handed a message to match on.
+ */
+type SessionStartFailureCode = /** The adapter refused or threw; the reservation was rolled back or retired. */'start-failed'
+/**
+ * The connector is live but another generation owns the provider session it
+ * speaks to. The connector was stopped and the claims retired.
+ */
+| 'ownership-refused' /** The agent row is `disposed` or gone; the connector was stopped. */ | 'agent-unavailable'
+/**
+ * The settlement neither landed nor was refused on ownership grounds — a raw
+ * throw from one of its guarded acts, not a modeled answer. The attempt is
+ * torn down on the caller-owned paths: the connector is stopped best-effort,
+ * the attempt's tokens are retired as `abandoned`, and the row is committed
+ * `dead` — the durable state must not advertise a start whose settlement
+ * this process can no longer vouch for.
+ */
+| 'settlement-unresolved' /** A joined start left the row `starting` more often than the bounded re-read allows. */ | 'start-unresolved' /** Another start won the lead designation and the session still has no agents. */ | 'lead-conflict' /** The session lifecycle gate rejected the reservation before adapter dispatch. */ | 'session-not-active';
+/** A reserved start that did not end with a usable agent. */
+declare class SessionStartError extends Error {
+  readonly code: SessionStartFailureCode;
+  /**
+   * The named targets this call could not act for — exactly the set the
+   * `agent-unavailable` code refuses. Two producers fill it: a total deferral
+   * (every named agent's provider session is held by a generation this runtime
+   * does not own) and a stated-target send against a session with no agents
+   * (the named agents do not exist). The field deliberately does not separate
+   * the two, because the code does not either: which one it was is a statement
+   * about the session, carried by the message, not a distinct caller branch —
+   * in particular, no entry is guaranteed to be foreign-held-and-retryable.
+   *
+   * A response field is unreachable on a path that throws, and a send that
+   * silently reaches fewer agents than it was asked to is exactly the failure
+   * this contract refuses everywhere else. The field carries the set for
+   * in-process callers; the message names the agents as well, for anything
+   * crossing a transport that may not preserve custom error properties.
+   */
+  readonly deferredAgentIds?: readonly string[];
+  /** Stored lifecycle status when the admission gate rejected a reservation. */
+  readonly sessionStatus?: 'closed' | 'archived' | 'discovered';
+  /**
+   * @param code - Which modeled outcome this is; the value callers branch on.
+   * @param message - Human-readable detail, including the identifiers involved.
+   * @param cause - Underlying failure, when one exists.
+   * @param deferredAgentIds - The named targets this call could not act for, when the send named any.
+   * @param sessionStatus - Non-active session status observed by a refused reservation.
+   */
+  constructor(code: SessionStartFailureCode, message: string, cause?: unknown, deferredAgentIds?: readonly string[], sessionStatus?: 'closed' | 'archived' | 'discovered');
+}
+//#endregion
 //#region services/core/src/session/handlers/abandon-handler.d.ts
 /**
  * Registers the session.abandon RPC handler.
@@ -602,6 +814,116 @@ declare function registerForkHandler(bus: IMakaioBus, machineId?: string): () =>
  */
 declare function registerMergeHandler(bus: IMakaioBus): () => void;
 //#endregion
+//#region services/core/src/session/handlers/in-flight-start-join.d.ts
+/** What a consumer does with an agent whose start it joined or arbitrated. */
+type StartResolution = /** The agent is usable as it stands. */'use' /** The agent is not part of this send: the row is gone, or terminal. */ | 'drop' /** The agent belongs to a guarded recovery this runtime cannot prove retired. */ | 'defer' /** The agent needs the ordinary fresh-with-history recovery. */ | 'recover';
+/** How a send's target set changed once every in-flight start was resolved. */
+interface InFlightStartResolution {
+  /** Agents that left the session's target set — deleted or `disposed` rows. */
+  readonly droppedAgentIds: ReadonlySet<string>;
+  /** Agents this send must recover before using. */
+  readonly recoveringAgentIds: ReadonlySet<string>;
+  /** Agents whose guarded recovery is owned by an unretired or unknown runtime. */
+  readonly deferredAgentIds: ReadonlySet<string>;
+  /**
+   * The subset whose recovery this send claimed by **compare-and-swap**, not by
+   * consuming a local attempt.
+   *
+   * The two provenances carry different evidence and must not be treated alike.
+   * A locally joined attempt reported its own verdict: this process ran it, and
+   * it said whether a connector exists. A won compare-and-swap says only that
+   * this caller wrote a status first — the attempt it outran belongs to a
+   * process this runtime cannot see, and Wave 3 has no way to ask whether that
+   * process is alive (OQ-B, deferred to Wave 4). Writing `dead` does not make
+   * the agent dead, so a consumer must still find out for itself before opening
+   * a second lifecycle.
+   */
+  readonly arbitratedAgentIds: ReadonlySet<string>;
+}
+/**
+ * Apply the in-flight-start consumer rule to a session's agents.
+ *
+ * Runs *before* the liveness probe and before the fresh-start branch, and only
+ * for agents whose stored status is `starting`. When this process waits for one
+ * of those starts, every materialized row is re-read to a stable pass;
+ * otherwise they cost nothing.
+ * The ordering matters at both ends: probing a `starting` agent would find no
+ * registered connector and walk into a second lifecycle for an identity that
+ * already has one in flight, and an agent dropped here may be the session's last,
+ * which must then start fresh rather than fail for having no targets.
+ *
+ * Dropped agents are removed from `session.agents` in place, and every agent that
+ * survives is **replaced by the row this resolution read**, so every later step
+ * of the send sees both the target set and the identities this resolution
+ * produced. A local join also refreshes every materialized row: every one was
+ * read before the wait, and the send probes and routes at all of their
+ * identities afterwards. The second half matters as much as the first: a joined
+ * attempt can bind an agent to a different adapter instance, and a send that
+ * kept the pre-join snapshot would probe liveness and route at the instance the
+ * lifecycle moved off.
+ * @param bus - Bus the joins, reads and compare-and-swaps are issued on.
+ * @param session - Session whose agents are resolved; its `agents` are filtered and refreshed in place.
+ * @returns Which agents left the set, and which the send must recover.
+ */
+declare function resolveInFlightStarts(bus: IMakaioBus, session: IMakaioSession): Promise<InFlightStartResolution>;
+//#endregion
+//#region services/core/src/session/handlers/deferred-agents.d.ts
+/**
+ * Admit a send to the fresh-start branch, or refuse the targets it stated.
+ *
+ * **Decided before that branch runs, and the ordering is the whole point.**
+ * `lead-default` is the only form that asks for *an* agent rather than asserting
+ * something about the ones the session has; every other form states a target,
+ * and a session with no agents answers every such statement the same way. So
+ * only `lead-default` may bring a session its first agent:
+ *
+ * - **`explicit`** — the session cannot contain the ids the caller named, and
+ *   substituting a freshly started agent would answer a question nobody asked.
+ * - **`'all'`** — "all of them" of nothing is not a delivery, exactly as it is
+ *   not one when every target defers ({@link refuseTotalDeferral}).
+ *
+ * Either send was already decided at this moment, so starting a lead first only
+ * changes *what the failure leaves behind* — an agent row, a lead designation
+ * and a reserved provider session created by a send that never delivered.
+ *
+ * This admits, it does not clear: a named agent the session *has* may still turn
+ * out to be undrivable, which is what the post-recovery validation decides.
+ *
+ * `agent-unavailable` is reused rather than invented, exactly as
+ * {@link refuseTotalDeferral} reuses it: the code means "this runtime may not act
+ * for these agents", and an agent that does not exist is the strongest form of
+ * that, not a different fact. Only the named form carries `deferredAgentIds` — a
+ * throw makes the response field unreachable, so the ids travel on the error
+ * where there are ids to travel; a broadcast named none, and inventing a payload
+ * for it would say the session held agents it never held.
+ * @param caller - Log prefix of the send path raising this, e.g. `[session.sendMessage]`.
+ * @param sessionId - Session the send was for.
+ * @param session - Session as this send resolved it, after any in-flight start.
+ * @param targetSpec - The request's `agentIds`, as the schema models it.
+ * @throws A {@link SessionStartError} naming the agents, when the send named any.
+ */
+declare function admitFreshStartTargets(caller: string, sessionId: string, session: IMakaioSession, targetSpec: readonly string[] | 'all' | undefined): void;
+/**
+ * Refuse a send whose every target is held elsewhere.
+ *
+ * `agent-unavailable` is reused rather than invented: it already means "this
+ * runtime may not act for this agent". A broadcast with no recipient is not a
+ * delivery, and a caller that named its agents is owed the failure rather than
+ * a substitute.
+ *
+ * **Exported for the send pipelines a product composes itself.** *Whether* a
+ * total deferral is a refusal is a product decision — this framework's
+ * orchestrator and a product's may guard it differently — but the refusal it
+ * raises is one fact with one wording and one code, and a second copy of it is a
+ * second answer to "what did the caller just fail with". The caller names itself
+ * so the message still says where the send stopped.
+ * @param caller - Log prefix of the send path raising this, e.g. `[session.sendMessage]`.
+ * @param sessionId - Session the send was for.
+ * @param deferredAgentIds - Agents held by a generation this runtime does not own.
+ * @throws A {@link SessionStartError} naming the agents in both the field and the message.
+ */
+declare function refuseTotalDeferral(caller: string, sessionId: string, deferredAgentIds: ReadonlySet<string>): never;
+//#endregion
 //#region services/core/src/session/handlers/routing-lifecycle.d.ts
 /** Narrow ledger transition owned by SessionTurnManager and injected into routing. */
 interface TurnCompletionRecorder {
@@ -722,4 +1044,4 @@ declare function routeToAgentsCore(bus: IMakaioBus, session: IMakaioSession, age
   adapterId: string;
 }>, message: MessageInput, messageId: string, turn: Turn$1, deliveryMode: 'enqueue' | 'immediate' | undefined, onTurnComplete: TurnCompleteCallback, turnManager: TurnCompletionRecorder, sessionContext?: SessionContext, responseSchema?: ResponseSchemaDescriptor, assertDispatch?: () => void): Promise<readonly AgentDispatchOutcome[]>;
 //#endregion
-export { registerCompressHandler as a, SessionTurnManager as c, TurnContext as d, TurnPairStateChange as f, registerForkHandler as i, Turn$1 as l, TurnResult as m, routeToAgents as n, registerAttachHandler as o, TurnPairTerminalOutcome as p, registerMergeHandler as r, registerAbandonHandler as s, routeToAgentsCore as t, TurnConfig as u };
+export { SessionTurnManager as C, TurnPairStateChange as D, TurnContext as E, TurnPairTerminalOutcome as O, resolveOwnedAdapterInstance as S, TurnConfig as T, OwnedAdapterInstanceTarget as _, InFlightStartResolution as a, resolveExecutionTarget as b, registerMergeHandler as c, registerAttachHandler as d, registerAbandonHandler as f, OwnedAdapterInstance as g, MachineScopedAdapterInstance as h, refuseTotalDeferral as i, TurnResult as k, registerForkHandler as l, SessionStartFailureCode as m, routeToAgents as n, StartResolution as o, SessionStartError as p, admitFreshStartTargets as r, resolveInFlightStarts as s, routeToAgentsCore as t, registerCompressHandler as u, resolveAdapterId as v, Turn$1 as w, resolveModelCapabilities as x, resolveAnnouncedAdapterInstance as y };