@opengeni/db 0.14.3 → 0.16.2

package/dist/schema.js

@@ -38,12 +38,19 @@ import {
   machineMetricsLatest,
   machineMetricsSeries,
   managedAccounts,
+  modelCallFacts,
   nestedAgentDepthConfiguration,
   newSessionDrafts,
   packInstallations,
+  preferenceRegistryEvents,
+  preferenceRegistryPreferences,
+  preferenceRegistryRevisions,
+  preferenceRegistrySnapshots,
   rigChanges,
   rigVersions,
   rigs,
+  sandboxCheckpointArtifactStateValues,
+  sandboxCheckpointArtifacts,
   sandboxKindValues,
   sandboxLeaseHolders,
   sandboxLeaseLivenessValues,
@@ -79,6 +86,7 @@ import {
   sessionTurns,
   sessionWorkflowWakeOutbox,
   sessions,
+  slackBotDeleteOperations,
   slackBotPostOperations,
   socialConnections,
   socialPosts,
@@ -97,7 +105,7 @@ import {
   workspaceVariableSetVariables,
   workspaceVariableSets,
   workspaces
-} from "./chunk-DW24CKCT.js";
+} from "./chunk-HZD7KVAR.js";
 import "./chunk-PZ5AY32C.js";
 export {
   agentRunStates,
@@ -139,12 +147,19 @@ export {
   machineMetricsLatest,
   machineMetricsSeries,
   managedAccounts,
+  modelCallFacts,
   nestedAgentDepthConfiguration,
   newSessionDrafts,
   packInstallations,
+  preferenceRegistryEvents,
+  preferenceRegistryPreferences,
+  preferenceRegistryRevisions,
+  preferenceRegistrySnapshots,
   rigChanges,
   rigVersions,
   rigs,
+  sandboxCheckpointArtifactStateValues,
+  sandboxCheckpointArtifacts,
   sandboxKindValues,
   sandboxLeaseHolders,
   sandboxLeaseLivenessValues,
@@ -180,6 +195,7 @@ export {
   sessionTurns,
   sessionWorkflowWakeOutbox,
   sessions,
+  slackBotDeleteOperations,
   slackBotPostOperations,
   socialConnections,
   socialPosts,

package/dist/session-control.d.ts

@@ -0,0 +1,331 @@
+import { type SessionMcpApprovalPolicy, type TurnInitiatorContext } from "@opengeni/contracts";
+import type { Database } from "./index";
+import * as schema from "./schema";
+export declare const SESSION_ANCESTRY_LIMIT = 10000;
+export type WorkspaceControlLockMode = "none" | "share" | "update";
+export type EffectiveControlState = "active" | "paused";
+export type SessionCommandActor = {
+    type: "human" | "operator";
+    subjectId: string;
+} | {
+    type: "service";
+    subjectId: string;
+    subjectLabel?: string;
+    context?: TurnInitiatorContext;
+} | {
+    type: "agent_attempt";
+    attemptId: string;
+    sessionId: string;
+    turnId: string;
+    executionGeneration: number;
+};
+export type SessionTurnAttemptOutcome = "completed" | "failed" | "cancelled" | "superseded" | "requires_action" | "waiting_capacity" | "interrupted_recoverable" | "lease_lost_recoverable" | "pre_cutover_closed";
+export type EffectiveControlBlocker = {
+    kind: "session" | "workspace";
+    sessionId?: string;
+    displayName: string;
+    actor: string | null;
+    reason: string | null;
+    changedAt: Date | null;
+    revision: number;
+};
+export type EffectiveControlResumeOption = {
+    scope: "selected" | "session" | "workspace";
+    targetId?: string;
+    selectedStateAfter: EffectiveControlState;
+    remainingPrimaryBlocker?: EffectiveControlBlocker;
+    impactCopy: string;
+};
+export type EffectiveSessionControl = {
+    state: EffectiveControlState;
+    controlVersion: number;
+    controlEtag: string;
+    directState: EffectiveControlState;
+    primaryBlocker: EffectiveControlBlocker | null;
+    additionalBlockerCount: number;
+    blockers: EffectiveControlBlocker[];
+    resumeOptions: EffectiveControlResumeOption[];
+    override: {
+        rootSessionId: string;
+        revision: number;
+    } | null;
+    settlement: {
+        state: "stopping";
+        attemptCount: number;
+        interruptionPendingCount: number;
+        quiescencePendingCount: number;
+    } | null;
+};
+export declare const SESSION_DISCOVERY_CONTROL_TITLE_MAX_CHARS = 200;
+export declare const SESSION_DISCOVERY_CONTROL_TARGET_LIMIT = 100;
+/**
+ * Purpose-built control projection for session discovery. Full blocker evidence,
+ * actors/reasons, resume options, etags, and settlement state remain available
+ * from the ordinary session detail APIs; this shape is intentionally only what
+ * `sessions_list` renders.
+ */
+export type SessionDiscoveryControl = {
+    state: EffectiveControlState;
+    primaryBlocker: {
+        kind: "session" | "workspace";
+        sessionId?: string;
+        displayName: string;
+        displayNameOriginalChars: number;
+    } | null;
+    additionalBlockerCount: number;
+};
+export declare function serializeEffectiveSessionControl(control: EffectiveSessionControl): {
+    state: EffectiveControlState;
+    controlVersion: number;
+    controlEtag: string;
+    directState: EffectiveControlState;
+    additionalBlockerCount: number;
+    override: {
+        rootSessionId: string;
+        revision: number;
+    } | null;
+    settlement: {
+        state: "stopping";
+        attemptCount: number;
+        interruptionPendingCount: number;
+        quiescencePendingCount: number;
+    } | null;
+    primaryBlocker: (Omit<EffectiveControlBlocker, "changedAt"> & {
+        changedAt: string | null;
+    }) | null;
+    blockers: (Omit<EffectiveControlBlocker, "changedAt"> & {
+        changedAt: string | null;
+    })[];
+    resumeOptions: {
+        scope: "selected" | "session" | "workspace";
+        targetId?: string;
+        selectedStateAfter: EffectiveControlState;
+        impactCopy: string;
+        remainingPrimaryBlocker?: Omit<EffectiveControlBlocker, "changedAt"> & {
+            changedAt: string | null;
+        };
+    }[];
+};
+export type WorkspaceControlRow = {
+    workspaceId: string;
+    accountId: string;
+    revision: number | string;
+    workspaceState: string;
+    workspacePauseRevision: number | string | null;
+    reason: string | null;
+    changedBy: string | null;
+    changedAt: Date | string | null;
+};
+export type SessionCommandReceiptRow = typeof schema.sessionCommandReceipts.$inferSelect;
+export declare class SessionControlInvariantError extends Error {
+    readonly code = "SESSION_CONTROL_INVARIANT";
+    constructor(message: string);
+}
+export declare class SessionControlConflictError extends Error {
+    readonly code = "CONTROL_CHANGED";
+    constructor(message?: string);
+}
+export declare class SessionCommandIdempotencyError extends Error {
+    readonly code = "IDEMPOTENCY_KEY_REUSED";
+    constructor();
+}
+export declare class AgentCommandAuthorityError extends Error {
+    readonly code: "CALLER_STALE" | "CALLER_INTERRUPTED" | "SELF_OR_ANCESTOR_PAUSE" | "SELF_STEER";
+    constructor(code: "CALLER_STALE" | "CALLER_INTERRUPTED" | "SELF_OR_ANCESTOR_PAUSE" | "SELF_STEER", message: string);
+}
+export declare function assertAgentCommandAuthorityInTransaction(db: Database, input: {
+    workspaceId: string;
+    actor: Extract<SessionCommandActor, {
+        type: "agent_attempt";
+    }>;
+    targetSessionId: string;
+    action: "pause" | "resume" | "steer" | "message" | "goal";
+}): Promise<void>;
+export declare function canonicalSessionCommandHash(value: unknown): string;
+export declare function lockWorkspaceInferenceControl(db: Database, workspaceId: string, mode: WorkspaceControlLockMode): Promise<WorkspaceControlRow>;
+export type SessionEventWriteLockInput = {
+    workspaceId: string;
+    /**
+     * Control-aware writes take this lock first. Callers that already hold the
+     * workspace control row (for example a Pause mutation under FOR UPDATE) say
+     * `already_locked`; ordinary audit/title appends explicitly use `none`.
+     */
+    controlLock: WorkspaceControlLockMode | "already_locked" | "none";
+    /** Used only when a staged caller already established the workspace prefix. */
+    workspaceLock?: "key_share" | "already_locked";
+    sessionIds?: string[];
+    turnIds?: string[];
+    attemptIds?: string[];
+};
+export type SessionEventWriteLocks = {
+    control: WorkspaceControlRow | null;
+    workspace: typeof schema.workspaces.$inferSelect | null;
+    sessions: Array<typeof schema.sessions.$inferSelect>;
+    turns: Array<typeof schema.sessionTurns.$inferSelect>;
+    attempts: Array<typeof schema.sessionTurnAttempts.$inferSelect>;
+};
+/**
+ * Establish the one canonical lock prefix for every `session_events` writer:
+ *
+ *   workspace_inference_controls (when control-aware)
+ *     -> actual workspaces row FOR KEY SHARE
+ *     -> session rows FOR UPDATE, UUID ordered
+ *     -> exact turn rows FOR UPDATE, UUID ordered
+ *     -> exact attempt rows FOR UPDATE, UUID ordered
+ *
+ * `FOR KEY SHARE` is deliberate. Event inserts need the workspace key to remain
+ * stable for their FK, but they do not mutate the workspace. The old generic
+ * `FOR UPDATE` lock serialized unrelated sessions and inverted the activity
+ * path's session -> implicit workspace-FK edge.
+ *
+ * Complex lifecycle transactions may acquire allocator/control locks before
+ * this helper and may discover exact turn IDs only after locking the session.
+ * They use the explicit `already_locked` stages, while retaining the same
+ * monotonic table order. New event writers should prefer one complete call.
+ */
+export declare function lockSessionEventWriteRows(db: Database, input: SessionEventWriteLockInput): Promise<SessionEventWriteLocks>;
+export declare function registerSessionTurnAttemptClaim(db: Database, input: {
+    id: string;
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    executionGeneration: number;
+    temporalWorkflowId: string;
+    temporalWorkflowRunId: string;
+    temporalActivityId: string;
+    verifiedControlRevision: number;
+    mcpApprovalPolicies: Record<string, SessionMcpApprovalPolicy>;
+}): Promise<typeof schema.sessionTurnAttempts.$inferSelect>;
+/**
+ * Close the exact first-class owner while the caller still holds the owning
+ * session/turn locks. Every path that clears `session_turns.active_attempt_id`
+ * must call this in the same transaction; otherwise a later claim would either
+ * collide with a zombie live owner or have to weaken the ownership fence.
+ */
+export declare function closeSessionTurnAttemptInTransaction(db: Database, input: {
+    id: string;
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    executionGeneration: number;
+    outcome: SessionTurnAttemptOutcome;
+    closedAt?: Date;
+}): Promise<{
+    action: "closed" | "already_closed";
+}>;
+export declare function evaluateSessionControls(db: Database, workspaceId: string, sessionIds: string[], options?: {
+    lock?: WorkspaceControlLockMode;
+    /** Reuse a control row already locked before workspace/session/turn rows. */
+    workspaceControl?: WorkspaceControlRow | undefined;
+}): Promise<Map<string, EffectiveSessionControl>>;
+/**
+ * Return one compact aggregate row per target for `sessions_list`.
+ *
+ * Unlike `evaluateSessionControls`, the database boundary never returns a row
+ * per blocker/ancestor, nor does application code construct blocker or resume
+ * option arrays. The recursive walk carries no growing visited-path array: a
+ * missing ancestor stops below the limit, while a cycle cannot reach a root and
+ * therefore runs into the hard `SESSION_ANCESTRY_LIMIT`. The externally
+ * supplied target set is capped by `SESSION_DISCOVERY_CONTROL_TARGET_LIMIT`.
+ */
+export declare function evaluateSessionDiscoveryControls(db: Database, workspaceId: string, sessionIds: string[]): Promise<Map<string, SessionDiscoveryControl>>;
+export declare function evaluateSessionControl(db: Database, workspaceId: string, sessionId: string, options?: {
+    lock?: WorkspaceControlLockMode;
+    workspaceControl?: WorkspaceControlRow | undefined;
+}): Promise<EffectiveSessionControl>;
+export declare function reserveSessionCommandReceipt(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    actor: SessionCommandActor;
+    action: string;
+    targetSessionId: string | null;
+    targetTurnId: string | null;
+    operationKey: string;
+    canonicalRequestHash: string;
+    identityScope?: "actor" | "goal_operation";
+}): Promise<{
+    receipt: SessionCommandReceiptRow;
+    replay: boolean;
+}>;
+/** Register one exact post-commit Temporal nudge without encoding eligibility in
+ * the transport. The workflow re-reads canonical Postgres state; coalescing is
+ * revisioned so a lost or stale delivery cannot hide a later mutation. */
+export declare function registerSessionWorkflowWakeInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    temporalWorkflowId: string;
+    reason: string;
+}): Promise<number>;
+/**
+ * Internal producers share one outstanding session-level receipt. While a wake
+ * remains undelivered, another update makes that same batch richer instead of
+ * manufacturing another transport revision or sequential model turn.
+ */
+export declare function registerInternalUpdateWakeInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    temporalWorkflowId: string;
+}): Promise<{
+    wakeRevision: number;
+    shouldSignal: boolean;
+}>;
+export declare function updateSessionCommandReceiptResult(db: Database, receiptId: string, input: {
+    controlRevision?: number | null;
+    queueVersion?: number | null;
+    turnVersion?: number | null;
+    draftRevision?: number | null;
+    result: Record<string, unknown>;
+}): Promise<SessionCommandReceiptRow>;
+export type SessionControlMutationResult = {
+    receipt: SessionCommandReceiptRow;
+    control: EffectiveSessionControl;
+    sessionControlEventId: string;
+    workspaceControlEventId: string;
+    interruptionCount: number;
+    wakeCount: number;
+    replay: boolean;
+};
+export declare function mutateSessionControlInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    actor: SessionCommandActor;
+    operationKey: string;
+    action: "pause" | "resume";
+    reason?: string | null;
+    expectedControlEtag?: string | null;
+}): Promise<SessionControlMutationResult>;
+export declare function autoResumeSessionBranchInTransaction(db: Database, input: {
+    workspaceId: string;
+    sessionId: string;
+    actor: string;
+    reason: "human_send" | "human_steer" | "service_send" | "service_steer" | "agent_steer";
+    observedControlEtag?: string | null;
+}): Promise<{
+    revision: number;
+    control: EffectiveSessionControl;
+    changed: boolean;
+    workspaceControlEventId: string | null;
+}>;
+export type WorkspaceControlMutationResult = {
+    receipt: SessionCommandReceiptRow;
+    revision: number;
+    workspaceControlEventId: string;
+    workspaceState: EffectiveControlState;
+    interruptionCount: number;
+    wakeCount: number;
+    replay: boolean;
+};
+export declare function mutateWorkspaceControlInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    actor: SessionCommandActor;
+    operationKey: string;
+    action: "pause" | "resume";
+    reason?: string | null;
+    expectedRevision?: number | null;
+}): Promise<WorkspaceControlMutationResult>;

package/dist/session-queue-commands.d.ts

@@ -0,0 +1,186 @@
+import { ResourceRef, type LatencyMode, type ReasoningEffort, type TurnExecutionPolicyV1 } from "@opengeni/contracts";
+import type { Database } from "./index";
+import { type SessionCommandActor, type SessionCommandReceiptRow } from "./session-control";
+import * as schema from "./schema";
+export type QueueCommandConflictCode = "QUEUE_VERSION_CHANGED" | "QUEUE_PROMPT_STARTED" | "QUEUE_ANCHOR_CHANGED" | "PROMPT_CHANGED" | "DRAFT_CHANGED" | "DRAFT_NOT_EMPTY" | "EDIT_SOURCE_CHANGED";
+export declare class QueueCommandConflictError extends Error {
+    readonly code: QueueCommandConflictCode;
+    readonly current: {
+        queueVersion: number;
+        turnVersion?: number;
+        draftRevision?: number;
+    };
+    readonly name = "QueueCommandConflictError";
+    constructor(code: QueueCommandConflictCode, message: string, current: {
+        queueVersion: number;
+        turnVersion?: number;
+        draftRevision?: number;
+    });
+}
+export type ComposerDraftRow = typeof schema.composerDrafts.$inferSelect;
+export type QueuedTurnRow = typeof schema.sessionTurns.$inferSelect;
+export type QueueCommandResult = {
+    receipt: SessionCommandReceiptRow;
+    queueVersion: number;
+    items: QueuedTurnRow[];
+    eventIds: string[];
+    replay: boolean;
+};
+export type EditQueueCommandResult = QueueCommandResult & {
+    draft: ComposerDraftRow;
+};
+export type SteerQueueCommandResult = QueueCommandResult & {
+    interruptionCount: number;
+    workspaceControlEventId: string | null;
+};
+export type SubmitHumanPromptResult = {
+    receipt: SessionCommandReceiptRow;
+    queueVersion: number;
+    acceptedEventId: string;
+    eventIds: string[];
+    turnId: string;
+    wakeRevision: number;
+    interruptionCount: number;
+    workspaceControlEventId: string | null;
+    replay: boolean;
+};
+export type AgentInternalUpdateCommandResult = {
+    receipt: SessionCommandReceiptRow;
+    updateId: string;
+    eventIds: string[];
+    wakeRevision: number | null;
+    shouldSignal: boolean;
+    workflowId: string;
+    effectiveState: "active" | "paused";
+    interruptionCount: number;
+    workspaceControlEventId: string | null;
+    replay: boolean;
+};
+type SteerSupersessionResult = {
+    interruptionCount: number;
+    replacedTurn: typeof schema.sessionTurns.$inferSelect | null;
+    liveCurrentTurnId: string | null;
+    lastSequence: number;
+};
+/**
+ * One canonical replacement transition shared by human row/new-prompt Steer
+ * and Agent Steer. A live owner is interrupted and remains current until exact
+ * settlement; an ownerless approval/recovery/capacity turn is superseded now.
+ */
+export declare function supersedeSessionCurrentDirectionInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    activeTurnId: string | null;
+    actor: SessionCommandActor;
+    operationId: string;
+    controlRevision: number;
+    lastSequence: number;
+}): Promise<SteerSupersessionResult>;
+export declare function getComposerDraftInTransaction(db: Database, input: {
+    workspaceId: string;
+    sessionId: string;
+    subjectId: string;
+    lock?: boolean;
+}): Promise<ComposerDraftRow | null>;
+export declare function saveComposerDraftInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    subjectId: string;
+    expectedRevision: number;
+    text: string;
+    resources: ResourceRef[];
+    model: string;
+    reasoningEffort: ReasoningEffort;
+    latencyMode?: LatencyMode;
+}): Promise<ComposerDraftRow>;
+export declare function moveQueuedTurnInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    beforeTurnId: string | null;
+    expectedQueueVersion: number;
+    actor: SessionCommandActor;
+    operationKey: string;
+}): Promise<QueueCommandResult>;
+export declare function deleteSessionQueueItemInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    expectedTurnVersion: number;
+    actor: SessionCommandActor;
+    operationKey: string;
+    reason?: string | null;
+}): Promise<QueueCommandResult>;
+export declare function editQueuedTurnInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    subjectId: string;
+    expectedTurnVersion: number;
+    expectedDraftRevision: number;
+    replaceDraft: boolean;
+    actor: SessionCommandActor;
+    operationKey: string;
+}): Promise<EditQueueCommandResult>;
+export declare function steerQueuedTurnInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    expectedTurnVersion: number;
+    controlEtag?: string | null;
+    actor: SessionCommandActor;
+    operationKey: string;
+}): Promise<SteerQueueCommandResult>;
+export declare function submitHumanPromptInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    subjectId: string;
+    subjectLabel?: string;
+    actor: SessionCommandActor;
+    operationKey: string;
+    delivery: "send" | "steer";
+    controlEtag?: string | null;
+    expectedDraftRevision?: number | null;
+    text: string;
+    turnInstructions?: string | null;
+    resources: ResourceRef[];
+    model?: string | null;
+    reasoningEffort?: ReasoningEffort | null;
+    latencyMode?: LatencyMode | null;
+    reasoningEffortFallback: ReasoningEffort;
+    /** Trusted API/core admission snapshot. Omitted only by legacy low-level callers. */
+    turnExecutionPolicy?: TurnExecutionPolicyV1;
+    source: "user" | "api";
+    mcpCredentialUpdates?: Array<{
+        id: string;
+        headersEncrypted: Record<string, string>;
+    }>;
+}): Promise<SubmitHumanPromptResult>;
+export declare function sendAgentMessageInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    targetSessionId: string;
+    actor: Extract<SessionCommandActor, {
+        type: "agent_attempt";
+    }>;
+    operationKey: string;
+    text: string;
+}): Promise<AgentInternalUpdateCommandResult>;
+export declare function steerAgentSessionInTransaction(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    targetSessionId: string;
+    actor: Extract<SessionCommandActor, {
+        type: "agent_attempt";
+    }>;
+    operationKey: string;
+    instruction: string;
+}): Promise<AgentInternalUpdateCommandResult>;
+export {};

package/dist/session-tool-call-settlement.d.ts

@@ -0,0 +1,32 @@
+import type { SessionEvent } from "@opengeni/contracts";
+import type { Database } from "./index";
+export declare const TOOL_RESULT_TYPE_BY_CALL_TYPE: Readonly<Record<string, string>>;
+export declare function historyCallId(item: Record<string, unknown>): string | null;
+export declare function historyItemType(item: Record<string, unknown>): string | null;
+/** Provider-valid result for a started call whose durable outcome is unknown. */
+export declare function interruptedToolCallResult(input: {
+    callType: string;
+    callId: string;
+    callItem: Record<string, unknown>;
+    reason: string;
+}): Record<string, unknown> | null;
+export type ClosePendingSessionToolCallsInput = {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    reason: string;
+    sequence: number;
+    now: Date;
+};
+/**
+ * Close every unresolved raw tool call for a logical turn while its owning
+ * session/turn locks are held. Durable results win; otherwise the model gets an
+ * explicit interrupted/outcome-unknown result for protocols that can represent
+ * one. Repeated settlement is an exact no-op after ledger deletion.
+ */
+export declare function closePendingSessionToolCallsInTransaction(tx: Database, input: ClosePendingSessionToolCallsInput): Promise<{
+    sequence: number;
+    events: SessionEvent[];
+    closed: number;
+}>;

package/dist/turn-initiator.d.ts

@@ -0,0 +1,28 @@
+import { type TurnInitiator, type TurnInitiatorContext } from "@opengeni/contracts";
+import type { Database } from "./index";
+import type { SessionCommandActor } from "./session-control";
+export declare const UNATTRIBUTED_LEGACY_INITIATOR: TurnInitiator;
+export type FrozenTurnInitiator = {
+    initiator: TurnInitiator;
+    context: TurnInitiatorContext;
+};
+/**
+ * Bound agent provenance without discarding its causal authority. Once the
+ * chain exceeds the cap, retain the first hop and the newest hops in order;
+ * consumers can still identify the root attempt while recent diagnostics stay
+ * useful. The omitted middle is signalled separately by `viaTruncated`.
+ */
+export declare function clipAgentProvenanceHops(hops: Array<Record<string, unknown>>): Array<Record<string, unknown>>;
+export declare function initiatorContextForStorage(initiator: TurnInitiator, context?: TurnInitiatorContext): TurnInitiatorContext;
+export declare function initiatorFromStorage(kind: string, subjectId: string, context: TurnInitiatorContext): TurnInitiator;
+export declare function initiatorColumns(value: FrozenTurnInitiator): {
+    initiatorKind: TurnInitiator["kind"];
+    initiatorSubjectId: string;
+    initiatorContext: TurnInitiatorContext;
+};
+export declare function creatorColumns(value: FrozenTurnInitiator): {
+    createdByKind: TurnInitiator["kind"];
+    createdBySubjectId: string;
+    createdByContext: TurnInitiatorContext;
+};
+export declare function frozenInitiatorForCommandActor(db: Database, workspaceId: string, actor: SessionCommandActor, subjectLabel?: string): Promise<FrozenTurnInitiator>;