@makaio/framework 1.0.0-dev-1783282710723 → 1.0.0-dev-1783439621927

package/dist/{index-9b2_jXxq.d.mts → index-CwHP8Jxs.d.mts}

@@ -1,19 +1,19 @@
 import { r as ExecutionTarget } from "./schemas-D4zaFE2p.mjs";
-import { d as Turn$1 } from "./index-gAFwNiJT.mjs";
-import { a as PipelineStep, o as SessionEditorAction, t as ActionCategory } from "./types-BMS6yfLS.mjs";
+import { d as Turn$1 } from "./index-BvTd61i5.mjs";
+import { a as PipelineStep, o as SessionEditorAction, t as ActionCategory } from "./types-BNW5n6qm.mjs";
 import { z } from "zod";
 import * as _$_makaio_core0 from "@makaio/framework/core";
 import { ExtractSubjectPayload, SubjectDefinition } from "@makaio/framework/core";
 import { IMakaioBus } from "@makaio/framework/bus";
 import * as _$_makaio_contracts0 from "@makaio/framework/contracts";
-import { AIReasoningLevel, AdapterRuntimeOptions, BranchKind, ContextWindowState, ForkOptions, ForkTransforms, IMakaioSession, JsonValue, MakaioSessionAgent, MakaioSessionEvent, Message, MessageBlock, MessageInput, ReasoningLevelMap, SessionContext, SessionExtensionContext, SessionLineage, SessionLineageKind, SessionMessage, SessionMessageBlock, TurnInitiator } from "@makaio/framework/contracts";
+import { AIReasoningLevel, AdapterRuntimeOptions, BranchKind, ContextWindowState, ForkOptions, ForkTransforms, ICapabilityProvider, IMakaioSession, JsonValue, MakaioSessionAgent, MakaioSessionEvent, Message, MessageBlock, MessageInput, NativeLocalityVerdict, ReasoningLevelMap, SessionContext, SessionEventType, SessionExtensionContext, SessionLineage, SessionLineageKind, SessionMessage, SessionMessageBlock, SessionMessageOrigin, SessionSubjects, TurnIngestionMarker, TurnInitiator, TurnUsage } from "@makaio/framework/contracts";
 import { BaseService } from "@makaio/framework/service-base";
-import * as _$_makaio_storage_core0 from "@makaio/framework/storage";
 import * as _$drizzle_orm_sqlite_core0 from "drizzle-orm/sqlite-core";
 import * as _$drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
 import * as _$_makaio_storage_drizzle0 from "@makaio/framework/storage/drizzle";
 import { MakaioDatabase } from "@makaio/framework/storage/drizzle";
 import * as _$drizzle_orm0 from "drizzle-orm";
+import * as _$_makaio_storage_core0 from "@makaio/framework/storage";
 
 //#region services/core/src/session/session-service.d.ts
 /**
@@ -32,10 +32,11 @@ import * as _$drizzle_orm0 from "drizzle-orm";
  * `SessionStorageSubjects.*` subjects. Register appropriate storage handlers
  * (memory or drizzle) before creating this service.
  *
- * `SessionLogger` is intentionally NOT a dependency here: it persists session
- * lifecycle events consumed only by recovery context assembly, fork, merge,
- * compress, and purge — all host features. Host services declare
- * `SessionLogger` in their own dependency chain.
+ * Session lifecycle rows in `session_events` (agent.added, branch.created)
+ * are written by the subscription writers registered during init
+ * (see `registerSessionLifecycleEventWriters`); turn lifecycle rows are
+ * persisted inline at their emit sites. No separate logger component needs
+ * to be wired by hosts.
  * @example
  * ```typescript
  * import { MakaioBus } from '@makaio/framework/bus';
@@ -109,7 +110,7 @@ interface CoreSessionServiceHandlerDeps {
  * Registers the framework-core session service handlers:
  * `session.create`, `session.get`, `session.list`, `session.turn.await`,
  * `session.close`, `session.restartAgents`, `session.update`,
- * `session.archive`, `session.purge`, `session.registerExternal`,
+ * `session.archive`, `session.purge`,
  * `session.agent.added`, and `session.agent.removed`.
  *
  * These handlers cover the minimal, load-bearing session contract for the
@@ -155,8 +156,8 @@ interface ISessionOrchestrator {
  * 4. Verify agent liveness and build recovery context for dead agents
  *    (requestOptional `AdapterSubjects.getAgent` + `buildRecoveryContext`)
  * 5. Get or create turn (via `SessionTurnManager`)
- * 6. Generate message ID and store user message + routing records
- *    (requestOptional, fire-and-forget)
+ * 6. Generate message ID and store user message (awaited, persist-before-route)
+ *    + routing records (fire-and-forget)
  * 7. Emit `session.turn.started` + `session.user_message.sent`
  * 8. Route to agents (via `routeToAgentsCore`, single shared context)
  * 9. Return result with `messageId`, `turnId`, `sessionId`
@@ -181,13 +182,16 @@ declare class SessionOrchestrator implements ISessionOrchestrator {
   private readonly bus;
   private readonly turnManager;
   private readonly adapterRegistry;
+  private readonly machineId;
   /** Cleanup functions for bus subscriptions. */
   private readonly cleanups;
   /**
    * @param bus - Event bus used for handler registration and message routing
-   * @param _machineId - Machine identifier (reserved for future routing use)
+   * @param machineId - Stable machine identity forwarded to the attach handler
+   *   to drive native-locality decisions (resume locality evaluation, adapter
+   *   instance resolution).
    */
-  constructor(bus: IMakaioBus | undefined, _machineId: string);
+  constructor(bus: IMakaioBus | undefined, machineId: string);
   /**
    * Register the `session.sendMessage` RPC handler.
    *
@@ -198,7 +202,7 @@ declare class SessionOrchestrator implements ISessionOrchestrator {
    * 3. Resolve target agents
    * 4. Verify agent liveness and build recovery context for dead agents
    * 5. Get or create turn (via SessionTurnManager)
-   * 6. Generate message ID and store user message + routing records (fire-and-forget)
+   * 6. Generate message ID and store user message (awaited) + routing records (fire-and-forget)
    * 7. Emit turn.started + user_message.sent
    * 8. Route to agents (routeToAgentsCore, single shared context)
    * 9. Return result with messageId, turnId, sessionId
@@ -356,9 +360,10 @@ declare function normalizeToBlocks(message: MessageInput): SessionMessageBlock[]
  * @param providedSessionId - Session ID to look up
  * @param _sessionContext - Optional session context (scope fields removed in W1-A)
  * @param originWindowId - Window ID that initiated the session creation
+ * @param machineId - Machine identity to stamp on the session at creation time
  * @returns Session ID and session object
  */
-declare function getOrCreateSession(bus: IMakaioBus, providedSessionId: string, _sessionContext?: SessionContext, originWindowId?: string): Promise<{
+declare function getOrCreateSession(bus: IMakaioBus, providedSessionId: string, _sessionContext?: SessionContext, originWindowId?: string, machineId?: string): Promise<{
   sessionId: string;
   session: IMakaioSession;
 }>;
@@ -435,6 +440,15 @@ interface RecoveryConfig {
   cwd?: string;
   /** Model identifier (e.g., 'claude-sonnet-4-20250514', 'gpt-4o') */
   model?: string;
+  /**
+   * Provider-native session ID to resume.
+   *
+   * When set, the adapter creates the connector in native-resume mode so the
+   * provider session continues from where it left off. The caller is responsible
+   * for evaluating locality (machine identity, adapter capability, CWD match)
+   * before setting this field.
+   */
+  resumeAdapterSessionId?: string;
 }
 /**
  * Ensure agent cwd matches desired cwd, swapping connector if needed.
@@ -796,15 +810,24 @@ type FallbackRuntimeOptions = Pick<AdapterRuntimeOptions, 'cwd' | 'systemPrompt'
 declare function pickFallbackRuntimeOptions(payload: Partial<Pick<AdapterRuntimeOptions, 'cwd' | 'systemPrompt' | 'allowedTools' | 'disallowedTools'>>): FallbackRuntimeOptions;
 //#endregion
 //#region services/core/src/session/context/assemble-fork-context.d.ts
+/** Adapter capability signals required before emitting a native fork directive. */
+interface AssembleForkContextCapabilities {
+  /** Adapter declares provider-native fork support for the selected target. */
+  readonly adapterSupportsNativeFork: boolean;
+  /** Adapter declares support for provider-native mid-history/checkpoint fork. */
+  readonly midHistoryForkSupported: boolean;
+}
 /**
  * Assemble fork context for a session's first turn.
  *
  * For fork sessions on their first turn, this:
  * 1. Detects if this is a fork session (has parentSessionId)
  * 2. Checks if this is the first turn (via isNewTurn flag + storage query)
- * 3. Calls getFullConversation() to get projected context with transforms
- * 4. Converts SessionMessage[] to Message[] format
- * 5. Returns enriched SessionContext with messageHistory
+ * 3. Evaluates native locality for the source (parent) session
+ * 4a. If native: returns a fork directive without message history injection
+ * 4b. Otherwise: calls getFullConversation() to get projected context with transforms,
+ *     converts SessionMessage[] to Message[] format, and attaches the locality verdict
+ * 5. Returns enriched SessionContext
  *
  * If not a fork first turn, returns the original sessionContext unchanged.
  * @param bus - Bus instance for RPC calls
@@ -812,9 +835,24 @@ declare function pickFallbackRuntimeOptions(payload: Partial<Pick<AdapterRuntime
  * @param sessionId - Session ID
  * @param originalContext - Original sessionContext from payload
  * @param isNewTurn - Whether this is a new turn (avoids race with just-created turn record)
+ * @param localMachineId - Stable machine identity of the current host process
+ * @param capabilities - Adapter capability signals resolved by the caller
+ * @param targetCwd - Effective working directory for the new agent, overriding
+ *   `session.targetWorkingDirectory` in the locality check. Callers that resolve
+ *   a per-request cwd override (e.g. a send payload `cwd` field) must pass the
+ *   resolved value here so the native-fork evaluation and the eventual
+ *   `startAgent` call operate on the same cwd — preventing a mismatch where
+ *   locality is approved against the stored session cwd but the agent starts in
+ *   a different directory.
+ * @param targetAdapterName - Stable adapter type name of the target adapter.
+ *   Compared against the source session's adapterName to prevent cross-adapter
+ *   fork — sending a provider session ID to a different adapter type would
+ *   corrupt the conversation. Undefined when the caller cannot determine the
+ *   target adapter (e.g. route-to-agents with mixed adapters); in that case the
+ *   adapter-mismatch check is skipped.
  * @returns Enriched or original SessionContext
  */
-declare function assembleForkContext(bus: IMakaioBus, session: IMakaioSession, sessionId: string, originalContext?: SessionContext, isNewTurn?: boolean): Promise<SessionContext | undefined>;
+declare function assembleForkContext(bus: IMakaioBus, session: IMakaioSession, sessionId: string, originalContext?: SessionContext, isNewTurn?: boolean, localMachineId?: string, capabilities?: AssembleForkContextCapabilities, targetCwd?: string, targetAdapterName?: string): Promise<SessionContext | undefined>;
 //#endregion
 //#region services/core/src/session/session-bridge.d.ts
 declare class SessionBridge {
@@ -1158,6 +1196,7 @@ declare const AgentStorageNamespace: _$_makaio_storage_core0.StorageNamespaceDef
     request: z.ZodObject<{
       agentId: z.ZodString;
       adapterId: z.ZodOptional<z.ZodString>;
+      adapterSessionId: z.ZodOptional<z.ZodString>;
       cwd: z.ZodOptional<z.ZodString>;
       model: z.ZodOptional<z.ZodString>;
       allowedDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1767,6 +1806,7 @@ declare const AgentStorageSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.
     request: z.ZodObject<{
       agentId: z.ZodString;
       adapterId: z.ZodOptional<z.ZodString>;
+      adapterSessionId: z.ZodOptional<z.ZodString>;
       cwd: z.ZodOptional<z.ZodString>;
       model: z.ZodOptional<z.ZodString>;
       allowedDirectories: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1905,7 +1945,7 @@ declare const sessionStorageSchema: _$_makaio_storage_drizzle0.DialectSchema<{
         tableName: "sessions";
         dataType: "string";
         columnType: "SQLiteText";
-        data: "discovered" | "closed" | "active" | "archived";
+        data: "closed" | "discovered" | "active" | "archived";
         driverParam: string;
         notNull: true;
         hasDefault: false;
@@ -2443,6 +2483,42 @@ declare const sessionStorageSchema: _$_makaio_storage_drizzle0.DialectSchema<{
       }, {}, {
         length: number | undefined;
       }>;
+      isSidechain: _$drizzle_orm_sqlite_core0.SQLiteColumn<{
+        name: string;
+        tableName: "sessions";
+        dataType: "boolean";
+        columnType: "SQLiteBoolean";
+        data: boolean;
+        driverParam: number;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: undefined;
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {}>;
+      machineId: _$drizzle_orm_sqlite_core0.SQLiteColumn<{
+        name: "machine_id";
+        tableName: "sessions";
+        dataType: "string";
+        columnType: "SQLiteText";
+        data: string;
+        driverParam: string;
+        notNull: false;
+        hasDefault: false;
+        isPrimaryKey: false;
+        isAutoincrement: false;
+        hasRuntimeDefault: false;
+        enumValues: [string, ...string[]];
+        baseColumn: never;
+        identity: undefined;
+        generated: undefined;
+      }, {}, {
+        length: number | undefined;
+      }>;
     };
     dialect: "sqlite";
   }>;
@@ -2862,6 +2938,7 @@ type SearchSessionRow = {
   fork_transforms: string | null;
   target_working_directory: string | null;
   metadata: Record<string, JsonValue> | string | null;
+  machine_id: string | null;
 };
 /**
  * Filter parameters accepted by FTS search queries.
@@ -2982,7 +3059,8 @@ declare function getSessionAncestorChain(db: MakaioDatabase, sessionId: string):
  * Session events table schema.
  *
  * Stores immutable, append-only session events for unified history reconstruction.
- * Events are persisted by SessionLogger via storage service.
+ * Lifecycle rows are persisted at their emit sites via the session lifecycle
+ * event helpers (see session-lifecycle-events.ts).
  *
  * **Event Types:**
  * - Message references (type='message' with messageId FK to messages table)
@@ -3370,7 +3448,7 @@ declare function registerMemorySessionEventStorage(bus: IMakaioBus): () => void;
  */
 declare function registerDrizzleSessionEventStorage(bus: IMakaioBus, db: MakaioDatabase): () => void;
 //#endregion
-//#region services/core/src/session/session-logger.d.ts
+//#region services/core/src/session/session-lifecycle-events.d.ts
 /**
  * Transform function for event payloads before storage emission.
  * Use for redaction, PII filtering, or payload normalization.
@@ -3384,90 +3462,326 @@ declare function registerDrizzleSessionEventStorage(bus: IMakaioBus, db: MakaioD
  */
 type EventTransform = (event: MakaioSessionEvent) => MakaioSessionEvent | null;
 /**
- * Options for SessionLogger.
+ * Arguments for {@link appendSessionLifecycleEvent}.
  */
-interface SessionLoggerOptions {
+interface SessionLifecycleEventArgs {
+  /** Event type for classification (e.g. 'turn.started'). */
+  type: SessionEventType;
+  /** Session the event belongs to. */
+  sessionId: string;
+  /** Event payload to persist. */
+  payload: unknown;
   /**
-   * Transform function applied before storage emission.
-   * Return null to skip storage entirely.
-   * Note: Does not affect individual session.* subjects (see EventTransform docs).
-   * Default: identity (no transformation)
+   * Stable event identifier. Provide one when the caller needs idempotent
+   * retries; defaults to a fresh UUID per call.
    */
-  transform?: EventTransform;
+  eventId?: string;
+  /** Event timestamp (Unix ms). Defaults to `Date.now()`. */
+  timestamp?: number;
 }
 /**
- * Bridges session lifecycle events to storage layer for persistence.
- *
- * **Architecture (Normalized Message Model):**
- * - Messages: Stored in `messages` table via MessageStorageSubjects (by SessionOrchestrator/SessionBridge)
- * - SessionLogger: Stores LIFECYCLE events only — agent.added, turn.started, turn.completed
- *
- * **NO longer subscribes to user_message.* events** — user messages are now
- * first-class entities in the `messages` table, not embedded in event payloads.
- *
- * The correlation link is `session.agent.added` which maps:
- * `sessionId ↔ agentId ↔ adapterSessionId`
- *
- * Subscribes to:
- * - session.agent.added — correlation link for multi-agent reconstruction
- * - session.turn.started, session.turn.completed — turn lifecycle
- * - session.branch.created — branch creation audit trail
- *
- * Does NOT subscribe to session.branch.merged or session.squash — those
- * handlers (merge-handler, compress-handler) own their persistence directly
- * using a stable eventId so retries are idempotent.
+ * Append a session lifecycle row to `session_events`.
+ *
+ * Builds the {@link MakaioSessionEvent} envelope, applies the optional
+ * transform (null result skips persistence), then requests
+ * `storage:sessionEvent.append` via `requestOptional` so ephemeral mode
+ * (no session-event storage registered) degrades gracefully. A handled
+ * append failure propagates to the caller so emit sites can preserve the
+ * persist-before-emit contract.
+ *
+ * This is the single write path for lifecycle rows in `session_events`.
+ * It MUST NOT be used for `branch.merged` / `squash` — those handlers
+ * (merge-handler, compress-handler) own their own idempotent persistence
+ * with stable eventIds; double-writing here would duplicate rows.
+ * @param bus - Bus used to reach session-event storage
+ * @param args - Event envelope fields (type, sessionId, payload, optional eventId/timestamp)
+ * @param transform - Optional transform applied before persistence (return null to skip)
+ */
+declare function appendSessionLifecycleEvent(bus: IMakaioBus, args: SessionLifecycleEventArgs, transform?: EventTransform): Promise<void>;
+/**
+ * Payload of the canonical `session.turn.started` event.
+ */
+type SessionTurnStartedPayload = ExtractSubjectPayload<typeof SessionSubjects.turn.started>;
+/**
+ * Persist the `turn.started` lifecycle row, then emit `session.turn.started`.
+ *
+ * This is the only sanctioned emit path for live-path `session.turn.started`
+ * emissions (single-emitter discipline): the orchestration emit sites
+ * (SessionOrchestrator, attach handler, MakaioSession entity) all route
+ * through this helper so the `session_events` row is durable before any
+ * consumer observes the event (persist-before-emit). The turn ingestion seam
+ * (`ingestCompletedTurn`) is the one other sanctioned emitter — it batches
+ * both lifecycle rows before emitting and must not be rerouted through this
+ * helper (doing so would reorder its persist-before-emit batch).
+ * @param bus - Bus used for lifecycle persistence and event emission
+ * @param payload - The exact `session.turn.started` payload to persist and emit
+ */
+declare function emitSessionTurnStarted(bus: IMakaioBus, payload: SessionTurnStartedPayload): Promise<void>;
+/**
+ * Register subscription-based `session_events` writers for the lifecycle
+ * subjects that have no single emit site: `session.agent.added` (persisted as
+ * type `agent.added`, the sessionId ↔ agentId ↔ adapterSessionId correlation
+ * link) and `session.branch.created` (branch creation audit trail).
+ *
+ * `turn.started` / `turn.completed` rows are NOT written here — their emit
+ * sites persist inline ({@link emitSessionTurnStarted}, SessionTurnManager's
+ * completion barrier, the turn ingestion seam) so the row lands before the
+ * event fires.
+ *
+ * Deliberately does NOT subscribe to `session.branch.merged` or
+ * `session.squash`: the merge and compress handlers own their persistence
+ * directly and call `storage:sessionEvent.append` with a stable eventId so
+ * retries are idempotent. Subscribing here would duplicate those rows.
+ *
+ * Wired by `MakaioSessionService` during init, so the writers run in every
+ * host that composes the session package.
+ * @param bus - Bus to subscribe on and persist through
+ * @param transform - Optional transform applied before persistence (return null to skip)
+ * @returns Cleanup function cancelling both subscriptions
+ */
+declare function registerSessionLifecycleEventWriters(bus: IMakaioBus, transform?: EventTransform): () => void;
+//#endregion
+//#region services/core/src/session/turn-ingest.d.ts
+/**
+ * A message belonging to an ingested turn.
  *
- * Emits transformed events to `storage:sessionEvent.append` for persistence.
- * @example
- * ```typescript
- * // Basic usage - lifecycle events are emitted to storage:sessionEvent.append
- * const sessionLogger = new SessionLogger(MakaioBus);
- *
- * // With redaction transform (mainly for turn error messages)
- * const sessionLogger = new SessionLogger(MakaioBus, {
- *   transform: (event) => {
- *     // Redact sensitive info if needed
- *     return event;
- *   },
- * });
- * ```
+ * Mirrors the `storage:message.upsertByAdapterMessageId` request minus
+ * `sessionId` / `turnId`, which the seam supplies from the ingested turn.
  */
-declare class SessionLogger {
-  private readonly bus;
-  private readonly options;
-  private readonly cleanups;
-  private readonly transform;
-  constructor(bus?: IMakaioBus, options?: SessionLoggerOptions);
-  /**
-   * Emit a session event to storage layer.
-   *
-   * Creates event envelope, applies transform, and emits to storage subject.
-   * If transform returns null, event is skipped.
-   * @param eventType - Event type for classification
-   * @param sessionId - Session identifier
-   * @param payload - Event payload to persist
-   */
-  private emitStorageEvent;
-  /**
-   * Register a handler for a session event subject.
-   * @param subject - Subject definition to subscribe to
-   * @param eventType - Event type for persistence
-   */
-  private registerHandler;
+interface IngestTurnMessage {
+  /** Adapter's message ID (external record uuid) — the idempotency key. */
+  adapterMessageId: string;
+  /** Message role. */
+  role: 'user' | 'assistant';
+  /** Plain text content for FTS indexing. */
+  contentText: string;
+  /** Structured content blocks. */
+  blocks: SessionMessageBlock[];
+  /** Agent ID (for assistant messages). */
+  agentId?: string;
+  /** Adapter's session ID. */
+  adapterSessionId?: string;
+  /** Message timestamp (Unix ms). */
+  timestamp: number;
+  /** Origin of the message (e.g. voice/text). */
+  origin?: SessionMessageOrigin;
+}
+/**
+ * Parameters for {@link ingestCompletedTurn}.
+ */
+interface IngestCompletedTurnParams {
+  /** Makaio session the turn belongs to. */
+  sessionId: string;
   /**
-   * Register all session lifecycle event handlers.
-   *
-   * **Normalized Message Model:**
-   * - User messages are stored in `messages` table by SessionOrchestrator
-   * - Assistant messages are stored by SessionBridge on agent.complete
-   * - SessionLogger only stores LIFECYCLE events for audit/correlation
+   * Content-derived idempotency anchor — the adapterMessageId of the
+   * turn-start user message. Re-ingesting the same anchor is a no-op.
    */
-  private registerHandlers;
+  turnAnchorId: string;
+  /** Turn start timestamp (Unix ms). */
+  startedAt: number;
+  /** Turn completion timestamp (Unix ms). */
+  completedAt: number;
+  /** Final turn status. */
+  status: 'completed' | 'error';
+  /** Error message when status is 'error'. */
+  error?: string;
+  /** Aggregated token usage for the turn. */
+  usage?: TurnUsage;
+  /** Actor provenance of whoever started the turn. */
+  initiator?: TurnInitiator;
+  /** Whether this emission is live ingestion or historical backfill. */
+  ingestionMarker: TurnIngestionMarker;
+  /** Messages of the turn, in transcript order. */
+  messages: IngestTurnMessage[];
+}
+/**
+ * Result of {@link ingestCompletedTurn}.
+ */
+interface IngestCompletedTurnResult {
+  /** Makaio turn ID (stable across re-ingestion of the same anchor). */
+  turnId: string;
+  /** Monotonic per-session ordinal (stable across re-ingestion). */
+  turnNumber: number;
+  /** True on first ingestion; false when the anchor already existed. */
+  created: boolean;
+}
+/**
+ * Ingest an externally-completed turn: persist the turn row and its messages,
+ * then emit the canonical `session.turn.*` events exactly once.
+ *
+ * Steps (persist-before-emit by construction):
+ * 1. Upsert the turn row via `storage:turn.ingestCompleted` (anchor-keyed).
+ *    Uses `bus.request`, not `requestOptional`: import paths always run with
+ *    turn storage registered — a missing handler is a caller error and must
+ *    surface, not silently drop the turn.
+ * 2. Upsert every message via `storage:message.upsertByAdapterMessageId`
+ *    with the real `turnId`. NEVER `storage:message.append` — append mints
+ *    fresh messageIds and would break re-import idempotency.
+ * 3. When the turn's `session.turn.*` side effects have not completed yet:
+ *    persist `turn.started` / `turn.completed` lifecycle rows into
+ *    `session_events` (deterministic eventIds, idempotent appends), then emit
+ *    `session.turn.started` followed by `session.turn.completed`.
+ * 4. Return the stable `(turnId, turnNumber)` identity plus `created`.
+ *
+ * Both events are emitted AFTER all persistence resolves. This deliberately
+ * differs from the managed orchestration path, which emits `turn.started`
+ * before routing to agents: here the turn is already finished, so there is
+ * no in-progress phase to signal — and emitting only after persistence is
+ * what guarantees the four-point consumer contract (session row, completed
+ * turn row, `getByTurn`-queryable messages, complete event payload) holds
+ * at emission time.
+ *
+ * Invariants:
+ * - (a) Never touches SessionTurnManager in-memory state
+ *   (`activeTurns` / `completingSessions`) — the turn is already complete
+ *   and never passes through the live turn lifecycle.
+ * - (b) Re-ingestion of the same anchor is a storage no-op and re-emits
+ *   nothing once the `turn.completed` lifecycle row is durable. Emission is
+ *   NOT gated on the anchor claim alone: a prior ingestion that claimed the
+ *   anchor but failed before its side effects completed (partial message
+ *   upsert, lifecycle append failure) leaves that row absent, and the next
+ *   ingestion of the same anchor resumes the emission instead of suppressing
+ *   it forever. Executions are serialized per anchor so concurrent hook- and
+ *   watcher-triggered ingestion stays exactly-once. Residual window: a
+ *   process crash between the lifecycle append and the bus emit loses that
+ *   emission (the durable row already claims it) — an accepted at-most-once
+ *   bound absent a transactional outbox. Without session-event storage
+ *   registered, resume detection is impossible and emission falls back to
+ *   first-ingestion-only.
+ * - (c) The four-point consumer contract holds when `session.turn.*` fires.
+ *
+ * Guard: when `params.messages` is empty, event emission is skipped
+ * (contract point 3 — `getByTurn` — would be unfulfillable) and a warning is
+ * logged; the turn row still persists, and a later re-ingestion that carries
+ * messages emits via the resume path.
+ * @param bus - Bus used for storage requests and event emission
+ * @param params - Turn identity, completion state, marker, and messages
+ * @returns Stable turn identity and whether this call created the turn
+ */
+declare function ingestCompletedTurn(bus: IMakaioBus, params: IngestCompletedTurnParams): Promise<IngestCompletedTurnResult>;
+//#endregion
+//#region services/core/src/session/observed-session-ingestion.d.ts
+/**
+ * Minimal local mirror of the log-import bus subjects this component calls.
+ *
+ * The log-import service package depends on this package, so importing its
+ * subject definitions here would create a package cycle. Bus subjects are
+ * matched by fully-qualified name and payloads are validated against the
+ * schemas registered by the owning service at boot — these mirrored
+ * definitions are type carriers for the fields this component reads and
+ * writes, not a second source of truth. Canonical schemas live with the
+ * log-import service.
+ *
+ * Exported for tests that stub the log-import seam; not part of the public
+ * session API surface.
+ * @internal
+ */
+declare const LogImportTriggerSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.FlatSubjectDefinitions<"log-import", {
+  /** Mirror of `log-import.listImporters` (adapterName/clientId subset). */listImporters: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      importers: z.ZodArray<z.ZodObject<{
+        adapterName: z.ZodString;
+        clientId: z.ZodOptional<z.ZodString>;
+      }, z.core.$strip>>;
+    }, z.core.$strip>;
+  }; /** Mirror of `log-import.importFile` (path-addressable import trigger). */
+  importFile: {
+    request: z.ZodObject<{
+      filePath: z.ZodString;
+      adapterName: z.ZodString;
+      ingestionMarker: z.ZodOptional<z.ZodEnum<{
+        live: "live";
+        backfill: "backfill";
+      }>>;
+    }, z.core.$strip>;
+    response: z.ZodDiscriminatedUnion<[z.ZodObject<{
+      status: z.ZodLiteral<"imported">;
+      sessionId: z.ZodString;
+      messageCount: z.ZodNumber;
+      turnCount: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+      status: z.ZodLiteral<"skipped">;
+      reason: z.ZodEnum<{
+        "no-importer": "no-importer";
+        "file-missing": "file-missing";
+      }>;
+    }, z.core.$strip>], "status">;
+  }; /** Mirror of `log-import.importSession` (discovery-stub-based trigger). */
+  importSession: {
+    request: z.ZodObject<{
+      adapterSessionId: z.ZodString;
+      adapterName: z.ZodString;
+      ingestionMarker: z.ZodOptional<z.ZodEnum<{
+        live: "live";
+        backfill: "backfill";
+      }>>;
+    }, z.core.$strip>;
+    response: z.ZodObject<{
+      sessionId: z.ZodString;
+      messageCount: z.ZodNumber;
+    }, z.core.$strip>;
+  };
+}>, "log-import">;
+/**
+ * Check whether a stored session represents a metadata-only observed session.
+ *
+ * Plain discovery scans also use `importStatus: 'discovered'`; the client id
+ * distinguishes hook-observed metadata-only registrations from scan-discovered
+ * sessions that are still eligible for explicit lazy import.
+ * @param session - Stored session row
+ * @returns True when content import must be suppressed
+ */
+declare function isPolicyDiscoveredObservedSession(session: Pick<IMakaioSession, 'clientId' | 'importStatus'>): boolean;
+//#endregion
+//#region services/core/src/session/observed-session-ingestion-policy.d.ts
+/** Capability id used for observed-session ingestion policy providers. */
+declare const OBSERVED_SESSION_INGESTION_POLICY_CAPABILITY_ID = "observed-session-ingestion-policy";
+/** Import lifecycle status a policy can choose for an observed session. */
+type ObservedSessionIngestionPolicyImportStatus = 'tracking' | 'discovered';
+/** Decision returned by an observed-session ingestion policy provider. */
+interface ObservedSessionIngestionPolicyDecision {
+  /** `tracking` imports transcript content; `discovered` registers metadata only. */
+  readonly importStatus: ObservedSessionIngestionPolicyImportStatus;
+}
+/** Inputs available when deciding how an observed session should be ingested. */
+interface ObservedSessionIngestionPolicyInput {
+  /** Stable client id that emitted the observation. */
+  readonly clientId: string;
+  /** Observation source, such as `native-hook` or `adapter-derived`. */
+  readonly source: string;
+  /** External session id reported by the client runtime. */
+  readonly adapterSessionId: string;
+  /** Canonical importer adapter name that would own content import. */
+  readonly adapterName: string;
+  /** Working directory observed at session start, when available. */
+  readonly cwd?: string;
+  /** Transcript path observed from the client runtime, when available. */
+  readonly transcriptPath?: string;
+}
+/** Capability provider that decides observed-session content ingestion policy. */
+interface IObservedSessionIngestionPolicyProvider extends ICapabilityProvider {
   /**
-   * Stop the logger and clean up subscriptions.
+   * Decide whether an observed session should content-import or metadata-register only.
+   * @param input - Observed session identity and importer context
+   * @returns Ingestion policy decision
    */
-  destroy(): void;
+  decideObservedSessionIngestion(input: ObservedSessionIngestionPolicyInput): ObservedSessionIngestionPolicyDecision | Promise<ObservedSessionIngestionPolicyDecision>;
 }
+/**
+ * Register an observed-session ingestion policy provider.
+ * @param bus - Makaio bus instance
+ * @param provider - Policy provider to register
+ * @returns Promise that resolves after registration handlers have completed
+ */
+declare function registerObservedSessionIngestionPolicyProvider(bus: IMakaioBus, provider: IObservedSessionIngestionPolicyProvider): Promise<void>;
+/**
+ * Unregister an observed-session ingestion policy provider.
+ * @param bus - Makaio bus instance
+ * @param providerId - Policy provider id to remove
+ * @returns Promise that resolves after unregistration handlers have completed
+ */
+declare function unregisterObservedSessionIngestionPolicyProvider(bus: IMakaioBus, providerId: string): Promise<void>;
 //#endregion
 //#region services/core/src/session/import-cursors/schema.d.ts
 /**
@@ -3836,6 +4150,17 @@ declare const turnsDual: _$_makaio_storage_drizzle0.DualTable<"turns", {
    * Stored as hand-stringified JSON because turn.create uses a raw SQL CTE.
    */
   initiator: _$_makaio_storage_drizzle0.DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteTextBuilderInitial<"initiator", [string, ...string[]], number | undefined>, _$drizzle_orm_pg_core0.PgTextBuilderInitial<"initiator", [string, ...string[]]>>;
+  /**
+   * Content-derived idempotency anchor for turns ingested from external
+   * transcripts — the adapterMessageId (external record uuid) of the
+   * turn-start user message. NULL for turns created by the managed
+   * orchestration path (storage:turn.create).
+   *
+   * Backs the ON CONFLICT target of storage:turn.ingestCompleted so
+   * re-parsing the same transcript (including compaction re-reads from
+   * byte 0) resolves to the existing turn row and never renumbers.
+   */
+  turnAnchorId: _$_makaio_storage_drizzle0.DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteTextBuilderInitial<"turn_anchor_id", [string, ...string[]], number | undefined>, _$drizzle_orm_pg_core0.PgTextBuilderInitial<"turn_anchor_id", [string, ...string[]]>>;
 }>;
 /** SQLite face of the `turns` table (canonical schema). */
 declare const turns: _$drizzle_orm_sqlite_core0.SQLiteTableWithColumns<{
@@ -4007,6 +4332,25 @@ declare const turns: _$drizzle_orm_sqlite_core0.SQLiteTableWithColumns<{
     }, {}, {
       length: number | undefined;
     }>;
+    turnAnchorId: _$drizzle_orm_sqlite_core0.SQLiteColumn<{
+      name: "turn_anchor_id";
+      tableName: "turns";
+      dataType: "string";
+      columnType: "SQLiteText";
+      data: string;
+      driverParam: string;
+      notNull: false;
+      hasDefault: false;
+      isPrimaryKey: false;
+      isAutoincrement: false;
+      hasRuntimeDefault: false;
+      enumValues: [string, ...string[]];
+      baseColumn: never;
+      identity: undefined;
+      generated: undefined;
+    }, {}, {
+      length: number | undefined;
+    }>;
   };
   dialect: "sqlite";
 }>;
@@ -4271,7 +4615,7 @@ declare const messages: _$drizzle_orm_sqlite_core0.SQLiteTableWithColumns<{
       tableName: "messages";
       dataType: "string";
       columnType: "SQLiteText";
-      data: "text" | "voice" | "compact";
+      data: "text" | "compact" | "voice";
       driverParam: string;
       notNull: false;
       hasDefault: false;
@@ -4998,4 +5342,78 @@ declare function buildSessionContext(bus: IMakaioBus, options: BuildContextOptio
  */
 declare function getFullConversation(bus: IMakaioBus, sessionId: string): Promise<ContextAssemblyResult>;
 //#endregion
-export { fetchMessageCountsBySession as $, registerMemoryTurnStorage as A, RecoveryConfig as At, registerMemorySessionEventStorage as B, findTurnByAgent as Bt, messages as C, registerGetStatusCountsHandler as Ct, SelectTurn as D, ContextWindowTrackerConfig as Dt, InsertTurn as E, AgentContextState as Et, importCursorsDual as F, verifyAndRecoverAgents as Ft, getSessionAncestorChain as G, TurnContextEnricher as Gt, SelectSessionEvent as H, resolveTargetAgents as Ht, EventTransform as I, buildRecoveryContext as It, mapAgentsBySession as J, SessionOrchestrator as Jt, SessionPreviewMaps as K, AdapterRegistry as Kt, SessionLogger as L, resolveAdapterId as Lt, EmbeddingIndexManager as M, ensureAgentCwd as Mt, registerDrizzleImportCursorStorage as N, ensureAgentModel as Nt, turns as O, SessionContextWindowState as Ot, importCursors as P, recoverAgent as Pt, fetchAgentsBySession as Q, SessionLoggerOptions as R, resolveExecutionTarget as Rt, SelectMessage as S, actionRegistry as St, registerDrizzleMessageStorage as T, ContextWindowTracker as Tt, sessionEvents as U, extractTextContent as Ut, InsertSessionEvent as V, getOrCreateSession as Vt, sessionEventsDual as W, normalizeToBlocks as Wt, SearchFilters as X, MakaioSessionService as Xt, mapToSession as Y, registerCoreSessionServiceHandlers as Yt, SearchSessionRow as Z, messageRoutingDual as _, normalizeSelectionString as _t, kindToBranchKind as a, registerMemoryAgentStorage as at, MessageRoutingSubjects as b, registerBuiltInActions as bt, registerSpawningToolCallResolver as c, AgentStorageNamespace as ct, MakaioSession as d, createSessionExtensionContext as dt, fetchPreviewBySession as et, MakaioSessionConfig as f, SessionBridge as ft, messageRouting as g, CONNECTOR_SWAP_DEFAULT_PIPELINE as gt, SelectMessageRouting as h, pickFallbackRuntimeOptions as ht, ContextAssemblyResult as i, registerDrizzleAgentStorage as it, registerDrizzleTurnStorage as j, buildRecoveryContextWithPipeline as jt, turnsDual as k, buildTurnInitiator as kt, registerCompressLineageResolver as l, AgentStorageSubjects as lt, InsertMessageRouting as m, FallbackRuntimeOptions as mt, buildSessionContext as n, parseForkTransforms as nt, toSessionLineage as o, registerDrizzleSessionStorage as ot, StartTurnOptions as p, assembleForkContext as pt, fetchSessionPreviewMaps as q, ISessionOrchestrator as qt, BuildContextOptions as r, registerFtsSearchHandler as rt, registerSessionDiscoveredHandler as s, registerMemorySessionStorage as st, getFullConversation as t, mapRowToSession as tt, registerParentResolver as u, SessionExtensionContextImpl as ut, registerDrizzleMessageRoutingStorage as v, resolveAdapterNameById as vt, registerMemoryMessageStorage as w, registerResumeHandler as wt, InsertMessage as x, resetBuiltInActionsRegistration as xt, MessageRoutingNamespace as y, registerListActionsHandler as yt, registerDrizzleSessionEventStorage as z, resolveModelCapabilities as zt };
+//#region services/core/src/session/native-locality.d.ts
+/**
+ * Describes whether the session resume/fork intent is a native continuation
+ * or a new fork branching from an existing session.
+ */
+type NativeLocalityIntent = 'resume' | 'fork';
+/**
+ * All inputs required for the native locality evaluator.
+ */
+interface NativeLocalityInput {
+  /** Whether this is a resume or fork operation. */
+  readonly intent: NativeLocalityIntent;
+  /** The session being resumed or forked. */
+  readonly session: IMakaioSession;
+  /**
+   * The stable machine identity of the current host process.
+   * Undefined when the framework host has not yet resolved machine identity.
+   */
+  readonly localMachineId: string | undefined;
+  /**
+   * Whether the adapter for this session declares native resume/fork capability.
+   * Adapters that cannot natively replay/branch must always inject history.
+   */
+  readonly adapterSupportsNative: boolean;
+  /**
+   * Stable adapter type name of the target adapter (e.g. 'claude-code', 'codex-mcp').
+   *
+   * Compared against `session.adapterName` to prevent cross-adapter resume/fork:
+   * sending a Claude provider session ID to a Codex adapter (or vice versa) would
+   * corrupt the provider conversation. When the session has no stored adapterName
+   * (legacy records, sessions created before adapter identity tracking), the check
+   * is skipped — the downstream adapter will reject an incompatible session ID.
+   */
+  readonly targetAdapterName: string;
+  /**
+   * Working directory of the current adapter instance.
+   * Only relevant when `targetCwd` is also supplied.
+   */
+  readonly currentCwd?: string;
+  /**
+   * Requested working directory for the resumed or forked session.
+   * When it differs from `currentCwd`, native operation cannot reuse the
+   * existing connector.
+   */
+  readonly targetCwd?: string;
+  /**
+   * Turn-scoped context signals produced by the session orchestrator.
+   * Used to detect compression, connector swaps, and pending transforms.
+   */
+  readonly sessionContext?: SessionContext;
+  /**
+   * Whether the underlying adapter supports forking at a mid-history message.
+   * Required when `session.forkPointMessageId` is set and `intent === 'fork'`.
+   */
+  readonly midHistoryForkSupported?: boolean;
+}
+/**
+ * Evaluates whether a session can use native resume or fork, or must fall back
+ * to history injection.
+ *
+ * Checks are ordered from cheapest/most common disqualifier to most specific so
+ * that callers pay no cost for conditions that are almost never hit:
+ *
+ * 1. Adapter capability declaration
+ * 2. Provider-native session ID presence
+ * 3. Machine identity availability and ownership
+ * 4. Structural constraints (imports + orchestration, compression, transforms,
+ *    connector swap, CWD mismatch)
+ * 5. Mid-history fork support
+ * @param input - All signals needed to determine locality
+ * @returns A {@link NativeLocalityVerdict} describing the outcome
+ */
+declare function evaluateNativeLocality(input: NativeLocalityInput): NativeLocalityVerdict;
+//#endregion
+export { SessionLifecycleEventArgs as $, recoverAgent as $t, SelectTurn as A, createSessionExtensionContext as At, OBSERVED_SESSION_INGESTION_POLICY_CAPABILITY_ID as B, resetBuiltInActionsRegistration as Bt, MessageRoutingSubjects as C, registerDrizzleAgentStorage as Ct, registerMemoryMessageStorage as D, AgentStorageNamespace as Dt, messages as E, registerMemorySessionStorage as Et, EmbeddingIndexManager as F, CONNECTOR_SWAP_DEFAULT_PIPELINE as Ft, unregisterObservedSessionIngestionPolicyProvider as G, AgentContextState as Gt, ObservedSessionIngestionPolicyImportStatus as H, registerGetStatusCountsHandler as Ht, registerDrizzleImportCursorStorage as I, normalizeSelectionString as It, IngestCompletedTurnParams as J, buildTurnInitiator as Jt, LogImportTriggerSubjects as K, ContextWindowTrackerConfig as Kt, importCursors as L, resolveAdapterNameById as Lt, turnsDual as M, assembleForkContext as Mt, registerMemoryTurnStorage as N, FallbackRuntimeOptions as Nt, registerDrizzleMessageStorage as O, AgentStorageSubjects as Ot, registerDrizzleTurnStorage as P, pickFallbackRuntimeOptions as Pt, EventTransform as Q, ensureAgentModel as Qt, importCursorsDual as R, registerListActionsHandler as Rt, MessageRoutingNamespace as S, registerFtsSearchHandler as St, SelectMessage as T, registerDrizzleSessionStorage as Tt, ObservedSessionIngestionPolicyInput as U, registerResumeHandler as Ut, ObservedSessionIngestionPolicyDecision as V, actionRegistry as Vt, registerObservedSessionIngestionPolicyProvider as W, ContextWindowTracker as Wt, IngestTurnMessage as X, buildRecoveryContextWithPipeline as Xt, IngestCompletedTurnResult as Y, RecoveryConfig as Yt, ingestCompletedTurn as Z, ensureAgentCwd as Zt, InsertMessageRouting as _, fetchAgentsBySession as _t, buildSessionContext as a, findTurnByAgent as an, registerMemorySessionEventStorage as at, messageRoutingDual as b, mapRowToSession as bt, kindToBranchKind as c, extractTextContent as cn, sessionEvents as ct, registerSpawningToolCallResolver as d, AdapterRegistry as dn, SessionPreviewMaps as dt, verifyAndRecoverAgents as en, SessionTurnStartedPayload as et, registerCompressLineageResolver as f, ISessionOrchestrator as fn, fetchSessionPreviewMaps as ft, StartTurnOptions as g, SearchSessionRow as gt, MakaioSessionConfig as h, MakaioSessionService as hn, SearchFilters as ht, getFullConversation as i, resolveModelCapabilities as in, registerDrizzleSessionEventStorage as it, turns as j, SessionBridge as jt, InsertTurn as k, SessionExtensionContextImpl as kt, toSessionLineage as l, normalizeToBlocks as ln, sessionEventsDual as lt, MakaioSession as m, registerCoreSessionServiceHandlers as mn, mapToSession as mt, NativeLocalityIntent as n, resolveAdapterId as nn, emitSessionTurnStarted as nt, BuildContextOptions as o, getOrCreateSession as on, InsertSessionEvent as ot, registerParentResolver as p, SessionOrchestrator as pn, mapAgentsBySession as pt, isPolicyDiscoveredObservedSession as q, SessionContextWindowState as qt, evaluateNativeLocality as r, resolveExecutionTarget as rn, registerSessionLifecycleEventWriters as rt, ContextAssemblyResult as s, resolveTargetAgents as sn, SelectSessionEvent as st, NativeLocalityInput as t, buildRecoveryContext as tn, appendSessionLifecycleEvent as tt, registerSessionDiscoveredHandler as u, TurnContextEnricher as un, getSessionAncestorChain as ut, SelectMessageRouting as v, fetchMessageCountsBySession as vt, InsertMessage as w, registerMemoryAgentStorage as wt, registerDrizzleMessageRoutingStorage as x, parseForkTransforms as xt, messageRouting as y, fetchPreviewBySession as yt, IObservedSessionIngestionPolicyProvider as z, registerBuiltInActions as zt };