bitfab 0.54.8 → 0.54.10

package/dist/index.d.cts

@@ -1,3 +1,25 @@
+/** One span the justification rests on, with what that span shows. */
+type JustificationSpan = {
+    spanId: string;
+    text: string;
+};
+/** Evidence for an assertion or a category: one entry per span relied on. */
+type Justification = JustificationSpan[];
+/** Whether a person has reviewed an assertion or a category. */
+type ApprovalState = "pending" | "approved" | "rejected";
+type Approver = {
+    id: string;
+    fullName: string | null;
+    email: string | null;
+    imageUrl: string | null;
+};
+/** Read-only on this client: only a person in Bitfab sets these. */
+type ApprovalFields = {
+    approvalState: ApprovalState;
+    approvedBy: Approver | null;
+    approvedAt: string | null;
+};
+
 declare class TraceCompletion {
     private readonly traces;
     private readonly closed;
@@ -308,6 +330,8 @@ interface ReplayContext {
      * signal that outputs must be fetched rather than read inline.
      */
     fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
+    /** Internal framework state captured on the historical root span. */
+    integrationFixtures?: Map<string, unknown>;
     dbBranchLease?: DbBranchLease;
     /**
      * Server-measured provisioning timings for this item's branch, echoed back
@@ -816,13 +840,20 @@ type AssertionCategorySummary = {
 };
 type AssertionCategory = AssertionCategorySummary & {
     organizationId: string;
+    /** Why this category is worth having, span by span. */
+    justification: Justification | null;
     createdAt: string;
     updatedAt: string;
-};
+} & ApprovalFields;
 type SaveAssertionCategoryParams = {
     id?: string;
     title: string;
     description?: string;
+    /**
+     * Why this category is worth having, one entry per span it rests on. Any span
+     * in the organization may be cited. Omit on an edit to preserve it.
+     */
+    justification?: Justification | null;
 };
 /** Organization-scoped groupings for assertions. */
 declare class AssertionCategoriesClient {
@@ -2175,6 +2206,88 @@ declare class ReplayBranch implements Omit<DbBranchLease, "databaseUrl"> {
     get databaseUrl(): string;
 }
 
+declare const RIVET_GROUP_EFFECT_METHODS: {
+    readonly db: readonly ["execute", "nativeMetrics", "close"];
+    readonly kv: readonly ["get", "put", "delete", "batchPut", "batchGet", "batchDelete", "deleteRange", "listPrefix", "listRange", "list"];
+    readonly schedule: readonly ["after", "at", "cancel", "get", "list"];
+    readonly cron: readonly ["set", "every", "get", "list", "delete", "history"];
+    readonly queue: readonly ["send", "next", "nextBatch", "waitForNames", "waitForAvailable", "complete", "enqueueAndWait", "tryNext", "tryNextBatch"];
+    readonly run: readonly ["setWakeAt"];
+};
+declare const RIVET_TOP_LEVEL_EFFECTS: readonly ["broadcast", "saveState", "sleep", "destroy"];
+type RivetGroup = keyof typeof RIVET_GROUP_EFFECT_METHODS;
+type RivetGroupEffectType = {
+    [TGroup in RivetGroup]: `${TGroup}.${(typeof RIVET_GROUP_EFFECT_METHODS)[TGroup][number]}`;
+}[RivetGroup];
+/** Finite Rivet context operations supported as replay effects. */
+type RivetEffectType = RivetGroupEffectType | (typeof RIVET_TOP_LEVEL_EFFECTS)[number] | "db.transaction.execute" | "queue.message.complete";
+/** Configuration for {@link BitfabRivetIntegration}. */
+interface RivetIntegrationOptions {
+    /**
+     * Context operations whose recorded outputs replay should serve instead of
+     * executing against a live actor. Nothing is marked by default.
+     */
+    mockOnReplay?: readonly RivetEffectType[];
+}
+/** Minimal structural context type used when callers do not supply Rivet's type. */
+interface RivetContextLike {
+    state: unknown;
+    readonly db: {
+        execute(...args: unknown[]): Promise<unknown>;
+    };
+    broadcast(name: string, ...args: unknown[]): void;
+    readonly actorId?: string;
+    readonly name?: string;
+    readonly key?: readonly string[];
+    readonly region?: string;
+}
+interface RivetIntegrationRuntime {
+    wrapEffect<TArgs extends unknown[], TReturn>(effect: RivetEffectType, mockOnReplay: boolean, fn: (...args: TArgs) => TReturn, replayOutput?: () => unknown): (...args: TArgs) => TReturn;
+    recordRootFixture(context: Record<string, unknown>, recordedRoots: Set<string>): void;
+}
+/**
+ * Binds a live Rivet actor context to an existing traced function and exposes
+ * replay-aware proxies for supported context operations.
+ *
+ * The integration never creates a trace root. Use it with the same
+ * `BitfabFunction` handle whose `withTrace()` wrapper is the production and
+ * replay root.
+ */
+declare class BitfabRivetIntegration<TContext extends object = RivetContextLike> {
+    private readonly traceFunctionKey;
+    private readonly runtime;
+    private readonly markedEffects;
+    private readonly replayProxies;
+    /** @internal Constructed by `Bitfab.getRivetIntegration()`. */
+    constructor(traceFunctionKey: string, runtime: RivetIntegrationRuntime, options?: RivetIntegrationOptions);
+    /**
+     * Run a callback with a live Rivet context bound to the current async chain.
+     * This binds context only; it creates no trace or span.
+     */
+    withContext<TReturn>(context: TContext, fn: () => TReturn): TReturn;
+    /**
+     * Adapt a traced function into a Rivet handler whose first argument is the
+     * live actor context. The context is not added to the traced root's inputs.
+     */
+    bind<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, context: TContext, ...args: TArgs) => TReturn;
+    /**
+     * Return the current Rivet context proxy. In production it delegates to the
+     * bound live context. During replay it hydrates recorded actor state and
+     * intercepts supported effects without requiring a live Rivet actor.
+     */
+    getContext(): TContext;
+    private createContextProxy;
+    private createDbProxy;
+    private createGroupProxy;
+    private createMethodProxy;
+    private createEffect;
+    private createTransaction;
+    private decorateQueueMessages;
+    private decorateQueueMessage;
+    private queueCallIsCompletable;
+    private createQueueIterator;
+}
+
 type TraceTargetOccurrence = "first" | "last" | number;
 type TraceTarget = {
     kind: "output";
@@ -2223,9 +2336,13 @@ type TraceAssertion = {
     failCriteria: string | null;
     targetOnEvaluatedTrace: TraceTarget | null;
     source: TraceAssertionSource;
+    /** Why this assertion is right for its trace, span by span. */
+    justification: Justification | null;
+    /** Why its assigned category is the right one, span by span. */
+    categoryJustification: Justification | null;
     createdAt: string;
     updatedAt: string;
-};
+} & ApprovalFields;
 type SaveAssertion = {
     /** Omit to preserve the category, or pass null to clear it. */
     category_assertion_id?: string | null;
@@ -2234,6 +2351,16 @@ type SaveAssertion = {
     passCriteria?: string | null;
     failCriteria?: string | null;
     targetOnEvaluatedTrace?: TraceTarget | null;
+    /**
+     * Why this assertion is right for this trace, one entry per span it rests on.
+     * Cite spans on this trace only. Omit on an edit to preserve it.
+     */
+    justification?: Justification | null;
+    /**
+     * Why `category_assertion_id` is the right category. Changing the category
+     * clears it. Omit on an edit to preserve it.
+     */
+    categoryJustification?: Justification | null;
 };
 type TraceAssertionsResult = {
     assertions: TraceAssertion[];
@@ -2995,6 +3122,16 @@ declare class Bitfab {
      * @experimental This API may change before it is stable.
      */
     getLangGraphIntegration(traceFunctionKey: string, options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
+    /**
+     * Get the first-class Rivet actor-context integration for an existing trace
+     * root. The integration binds context and records effect spans; it never
+     * creates another root.
+     *
+     * @param traceFunctionKey - Key used by the enclosing `withTrace()` root
+     * @param options - Explicit per-context-path replay mocking policy
+     * @experimental This API may change before it is stable.
+     */
+    getRivetIntegration<TContext extends object = RivetContextLike>(traceFunctionKey: string, options?: RivetIntegrationOptions): BitfabRivetIntegration<TContext>;
     /**
      * Get a Claude Agent SDK handler for tracing.
      *
@@ -3310,6 +3447,31 @@ declare class BitfabFunction {
      * @returns A standard ECMAScript method decorator
      */
     span(options?: SpanOptions): SpanMethodDecorator;
+    /**
+     * Wrap a function as an automatically expanded trace root bound to this
+     * function's key.
+     *
+     * Equivalent to `client.withTrace(key, options, fn)` but reuses the key
+     * bound on this handle.
+     *
+     * @param optionsOrFn - Trace options or the workflow entrypoint to wrap
+     * @param maybeFn - Workflow entrypoint when options are provided
+     * @returns A wrapped function with the same signature
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    withTrace<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    withTrace<This, TArgs extends unknown[], TReturn>(options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    /**
+     * Create a trace method decorator bound to this function's key.
+     *
+     * Equivalent to `client.trace(key, options)` but reuses the key bound on
+     * this handle.
+     *
+     * @param options - Trace configuration applied to the decorated method
+     * @returns A method decorator configured for this key
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    trace(options?: TraceOptions): TraceMethodDecorator;
     /**
      * Get a Vercel AI SDK language-model middleware bound to this function's key.
      *
@@ -3397,6 +3559,15 @@ declare class BitfabFunction {
      * @experimental This API may change before it is stable.
      */
     getLangGraphIntegration(options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
+    /**
+     * Get the first-class Rivet actor-context integration bound to this key.
+     * Use its `bind()` or `withContext()` outside this handle's `withTrace()`
+     * root, then call `getContext()` inside the root.
+     *
+     * @param options - Explicit per-context-path replay mocking policy
+     * @experimental This API may change before it is stable.
+     */
+    getRivetIntegration<TContext extends object = RivetContextLike>(options?: RivetIntegrationOptions): BitfabRivetIntegration<TContext>;
     /**
      * Wrap a BAML client method to automatically capture prompt and LLM metadata.
      * Delegates to the parent client's wrapBAML method.
@@ -3431,7 +3602,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.54.8";
+declare const __version__ = "0.54.10";
 
 /**
  * Constants for the Bitfab SDK.
@@ -3570,4 +3741,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionVerdict, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionVerdict, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };

package/dist/index.d.ts

@@ -1,3 +1,25 @@
+/** One span the justification rests on, with what that span shows. */
+type JustificationSpan = {
+    spanId: string;
+    text: string;
+};
+/** Evidence for an assertion or a category: one entry per span relied on. */
+type Justification = JustificationSpan[];
+/** Whether a person has reviewed an assertion or a category. */
+type ApprovalState = "pending" | "approved" | "rejected";
+type Approver = {
+    id: string;
+    fullName: string | null;
+    email: string | null;
+    imageUrl: string | null;
+};
+/** Read-only on this client: only a person in Bitfab sets these. */
+type ApprovalFields = {
+    approvalState: ApprovalState;
+    approvedBy: Approver | null;
+    approvedAt: string | null;
+};
+
 declare class TraceCompletion {
     private readonly traces;
     private readonly closed;
@@ -308,6 +330,8 @@ interface ReplayContext {
      * signal that outputs must be fetched rather than read inline.
      */
     fetchSpanOutput?: (externalSpanId: string) => Promise<unknown>;
+    /** Internal framework state captured on the historical root span. */
+    integrationFixtures?: Map<string, unknown>;
     dbBranchLease?: DbBranchLease;
     /**
      * Server-measured provisioning timings for this item's branch, echoed back
@@ -816,13 +840,20 @@ type AssertionCategorySummary = {
 };
 type AssertionCategory = AssertionCategorySummary & {
     organizationId: string;
+    /** Why this category is worth having, span by span. */
+    justification: Justification | null;
     createdAt: string;
     updatedAt: string;
-};
+} & ApprovalFields;
 type SaveAssertionCategoryParams = {
     id?: string;
     title: string;
     description?: string;
+    /**
+     * Why this category is worth having, one entry per span it rests on. Any span
+     * in the organization may be cited. Omit on an edit to preserve it.
+     */
+    justification?: Justification | null;
 };
 /** Organization-scoped groupings for assertions. */
 declare class AssertionCategoriesClient {
@@ -2175,6 +2206,88 @@ declare class ReplayBranch implements Omit<DbBranchLease, "databaseUrl"> {
     get databaseUrl(): string;
 }
 
+declare const RIVET_GROUP_EFFECT_METHODS: {
+    readonly db: readonly ["execute", "nativeMetrics", "close"];
+    readonly kv: readonly ["get", "put", "delete", "batchPut", "batchGet", "batchDelete", "deleteRange", "listPrefix", "listRange", "list"];
+    readonly schedule: readonly ["after", "at", "cancel", "get", "list"];
+    readonly cron: readonly ["set", "every", "get", "list", "delete", "history"];
+    readonly queue: readonly ["send", "next", "nextBatch", "waitForNames", "waitForAvailable", "complete", "enqueueAndWait", "tryNext", "tryNextBatch"];
+    readonly run: readonly ["setWakeAt"];
+};
+declare const RIVET_TOP_LEVEL_EFFECTS: readonly ["broadcast", "saveState", "sleep", "destroy"];
+type RivetGroup = keyof typeof RIVET_GROUP_EFFECT_METHODS;
+type RivetGroupEffectType = {
+    [TGroup in RivetGroup]: `${TGroup}.${(typeof RIVET_GROUP_EFFECT_METHODS)[TGroup][number]}`;
+}[RivetGroup];
+/** Finite Rivet context operations supported as replay effects. */
+type RivetEffectType = RivetGroupEffectType | (typeof RIVET_TOP_LEVEL_EFFECTS)[number] | "db.transaction.execute" | "queue.message.complete";
+/** Configuration for {@link BitfabRivetIntegration}. */
+interface RivetIntegrationOptions {
+    /**
+     * Context operations whose recorded outputs replay should serve instead of
+     * executing against a live actor. Nothing is marked by default.
+     */
+    mockOnReplay?: readonly RivetEffectType[];
+}
+/** Minimal structural context type used when callers do not supply Rivet's type. */
+interface RivetContextLike {
+    state: unknown;
+    readonly db: {
+        execute(...args: unknown[]): Promise<unknown>;
+    };
+    broadcast(name: string, ...args: unknown[]): void;
+    readonly actorId?: string;
+    readonly name?: string;
+    readonly key?: readonly string[];
+    readonly region?: string;
+}
+interface RivetIntegrationRuntime {
+    wrapEffect<TArgs extends unknown[], TReturn>(effect: RivetEffectType, mockOnReplay: boolean, fn: (...args: TArgs) => TReturn, replayOutput?: () => unknown): (...args: TArgs) => TReturn;
+    recordRootFixture(context: Record<string, unknown>, recordedRoots: Set<string>): void;
+}
+/**
+ * Binds a live Rivet actor context to an existing traced function and exposes
+ * replay-aware proxies for supported context operations.
+ *
+ * The integration never creates a trace root. Use it with the same
+ * `BitfabFunction` handle whose `withTrace()` wrapper is the production and
+ * replay root.
+ */
+declare class BitfabRivetIntegration<TContext extends object = RivetContextLike> {
+    private readonly traceFunctionKey;
+    private readonly runtime;
+    private readonly markedEffects;
+    private readonly replayProxies;
+    /** @internal Constructed by `Bitfab.getRivetIntegration()`. */
+    constructor(traceFunctionKey: string, runtime: RivetIntegrationRuntime, options?: RivetIntegrationOptions);
+    /**
+     * Run a callback with a live Rivet context bound to the current async chain.
+     * This binds context only; it creates no trace or span.
+     */
+    withContext<TReturn>(context: TContext, fn: () => TReturn): TReturn;
+    /**
+     * Adapt a traced function into a Rivet handler whose first argument is the
+     * live actor context. The context is not added to the traced root's inputs.
+     */
+    bind<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, context: TContext, ...args: TArgs) => TReturn;
+    /**
+     * Return the current Rivet context proxy. In production it delegates to the
+     * bound live context. During replay it hydrates recorded actor state and
+     * intercepts supported effects without requiring a live Rivet actor.
+     */
+    getContext(): TContext;
+    private createContextProxy;
+    private createDbProxy;
+    private createGroupProxy;
+    private createMethodProxy;
+    private createEffect;
+    private createTransaction;
+    private decorateQueueMessages;
+    private decorateQueueMessage;
+    private queueCallIsCompletable;
+    private createQueueIterator;
+}
+
 type TraceTargetOccurrence = "first" | "last" | number;
 type TraceTarget = {
     kind: "output";
@@ -2223,9 +2336,13 @@ type TraceAssertion = {
     failCriteria: string | null;
     targetOnEvaluatedTrace: TraceTarget | null;
     source: TraceAssertionSource;
+    /** Why this assertion is right for its trace, span by span. */
+    justification: Justification | null;
+    /** Why its assigned category is the right one, span by span. */
+    categoryJustification: Justification | null;
     createdAt: string;
     updatedAt: string;
-};
+} & ApprovalFields;
 type SaveAssertion = {
     /** Omit to preserve the category, or pass null to clear it. */
     category_assertion_id?: string | null;
@@ -2234,6 +2351,16 @@ type SaveAssertion = {
     passCriteria?: string | null;
     failCriteria?: string | null;
     targetOnEvaluatedTrace?: TraceTarget | null;
+    /**
+     * Why this assertion is right for this trace, one entry per span it rests on.
+     * Cite spans on this trace only. Omit on an edit to preserve it.
+     */
+    justification?: Justification | null;
+    /**
+     * Why `category_assertion_id` is the right category. Changing the category
+     * clears it. Omit on an edit to preserve it.
+     */
+    categoryJustification?: Justification | null;
 };
 type TraceAssertionsResult = {
     assertions: TraceAssertion[];
@@ -2995,6 +3122,16 @@ declare class Bitfab {
      * @experimental This API may change before it is stable.
      */
     getLangGraphIntegration(traceFunctionKey: string, options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
+    /**
+     * Get the first-class Rivet actor-context integration for an existing trace
+     * root. The integration binds context and records effect spans; it never
+     * creates another root.
+     *
+     * @param traceFunctionKey - Key used by the enclosing `withTrace()` root
+     * @param options - Explicit per-context-path replay mocking policy
+     * @experimental This API may change before it is stable.
+     */
+    getRivetIntegration<TContext extends object = RivetContextLike>(traceFunctionKey: string, options?: RivetIntegrationOptions): BitfabRivetIntegration<TContext>;
     /**
      * Get a Claude Agent SDK handler for tracing.
      *
@@ -3310,6 +3447,31 @@ declare class BitfabFunction {
      * @returns A standard ECMAScript method decorator
      */
     span(options?: SpanOptions): SpanMethodDecorator;
+    /**
+     * Wrap a function as an automatically expanded trace root bound to this
+     * function's key.
+     *
+     * Equivalent to `client.withTrace(key, options, fn)` but reuses the key
+     * bound on this handle.
+     *
+     * @param optionsOrFn - Trace options or the workflow entrypoint to wrap
+     * @param maybeFn - Workflow entrypoint when options are provided
+     * @returns A wrapped function with the same signature
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    withTrace<This, TArgs extends unknown[], TReturn>(fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    withTrace<This, TArgs extends unknown[], TReturn>(options: TraceOptions, fn: (this: This, ...args: TArgs) => TReturn): (this: This, ...args: TArgs) => TReturn;
+    /**
+     * Create a trace method decorator bound to this function's key.
+     *
+     * Equivalent to `client.trace(key, options)` but reuses the key bound on
+     * this handle.
+     *
+     * @param options - Trace configuration applied to the decorated method
+     * @returns A method decorator configured for this key
+     * @experimental Automatic child-call instrumentation is experimental.
+     */
+    trace(options?: TraceOptions): TraceMethodDecorator;
     /**
      * Get a Vercel AI SDK language-model middleware bound to this function's key.
      *
@@ -3397,6 +3559,15 @@ declare class BitfabFunction {
      * @experimental This API may change before it is stable.
      */
     getLangGraphIntegration(options?: LangGraphIntegrationOptions): BitfabLangGraphIntegration;
+    /**
+     * Get the first-class Rivet actor-context integration bound to this key.
+     * Use its `bind()` or `withContext()` outside this handle's `withTrace()`
+     * root, then call `getContext()` inside the root.
+     *
+     * @param options - Explicit per-context-path replay mocking policy
+     * @experimental This API may change before it is stable.
+     */
+    getRivetIntegration<TContext extends object = RivetContextLike>(options?: RivetIntegrationOptions): BitfabRivetIntegration<TContext>;
     /**
      * Wrap a BAML client method to automatically capture prompt and LLM metadata.
      * Delegates to the parent client's wrapBAML method.
@@ -3431,7 +3602,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.54.8";
+declare const __version__ = "0.54.10";
 
 /**
  * Constants for the Bitfab SDK.
@@ -3570,4 +3741,4 @@ declare function seedFromRegistry(registry: ReplayRegistry, pipeline: string, ca
     run?: boolean;
 }): Promise<SeedResult>;
 
-export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionVerdict, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };
+export { type ActiveSpanContext, type AdaptContext, type AdaptInputsFn, type AddDatasetGradersResult, type AddDatasetTracesResult, type AllowedEnvVars, type ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionVerdict, BITFAB_PROGRESS_PREFIX, type BamlExecutionResult, Bitfab, BitfabClaudeAgentHandler, type BitfabConfig, BitfabError, BitfabFunction, BitfabLangGraphCallbackHandler as BitfabLangChainCallbackHandler, BitfabLangGraphCallbackHandler, BitfabLangGraphIntegration, type BitfabLanguageModelMiddleware, BitfabOpenAIAgentHandler, BitfabOpenAITracingProcessor, BitfabRivetIntegration, BitfabVercelAiHandler, type CaptureSurface, type CaptureWhen, type CapturedSpan, type CodeChangeFile, type CommitRef, type CurrentSpan, type CurrentTrace, DEFAULT_SERVICE_URL, type Dataset, type DatasetGraderRef, type DatasetTraceIds, DatasetsClient, type DbBranchOptions, DbBranchReplayError, type DbBranchTimings, type DbSnapshotConfig, type DbSnapshotProvider, type DbSnapshotRef, type DetachedTrace, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelUpdate, LabelsClient, type LangGraphIntegrationOptions, type ListDatasetsParams, MixedTracingError, type MockOverride, type MockOverrideCtx, type MockOverrideInput, type MockOverrideResolver, type MockStrategy, type MockValue, NO_MOCK_OVERRIDE, type NodeMatcher, type NodeMethodDecorator, type NodeOptions, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayOptions, type ReplayOptionsFactory, type ReplayProgress, type ReplayProgressItem, type ReplayRegistration, type ReplayRegistry, type ReplayRegistryContext, type ReplayRegistryOptions, type ReplayResult, type RerunGradersOptions, type RerunGradersResult, type ReseedOptions, type ReseedRegistryResult, type ReseedResult, type RivetContextLike, type RivetEffectType, type RivetIntegrationOptions, SUPPORTED_PROVIDERS, type SaveAssertion, type SaveAssertionCategoryParams, type SaveAssertionsAllParams, type SaveAssertionsParams, type SaveDatasetParams, type SaveDatasetResult, type SeedCase, type SeedCaseOptions, type SeedResult, type SeedRunOptions, type SpanLookup, type SpanMethodDecorator, type SpanMethodDecoratorContext, type SpanNodeMeta, type SpanOccurrence, type SpanOptions, type SpanType, type TokenUsage, type TraceAssertion, type TraceAssertionSource, type TraceAssertionsResult, type TraceAssertionsUpdate, type TraceIngestionType, type TraceLabels, type TraceOutline, type TraceOutlineSpan, type TraceOutlineSpanError, type TraceResponse, type TraceSearchFilters, type TraceSearchParams, type TraceSearchResult, type TraceTarget, type TraceTargetOccurrence, TracesClient, type TracingProcessor, type VercelCallParams, type VercelGenerateResult, type VercelStreamResult, type WrapBAMLOptions, type WrappedBamlFn, __version__, defineReplayRegistry, finalizers, flushTraces, getCurrentReplayBranch, getCurrentSpan, getCurrentTrace, reportReplayProgress, reseedFromRegistry, seedFromRegistry, serializeReplayResult };

package/dist/index.js

@@ -16,6 +16,7 @@ import {
   BitfabLangGraphIntegration,
   BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
+  BitfabRivetIntegration,
   BitfabVercelAiHandler,
   DatasetsClient,
   GradersClient,
@@ -29,7 +30,7 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-XPCVDQDS.js";
+} from "./chunk-A3OBQOLV.js";
 import "./chunk-EGWJYCNT.js";
 import {
   BITFAB_PROGRESS_PREFIX,
@@ -38,7 +39,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-RUCVJQBI.js";
+} from "./chunk-PRXW4B5X.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -46,7 +47,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-5H3D7J4K.js";
+} from "./chunk-B2O33DBH.js";
 import "./chunk-VCRFFCLY.js";
 export {
   AssertionCategoriesClient,
@@ -60,6 +61,7 @@ export {
   BitfabLangGraphIntegration,
   BitfabOpenAIAgentHandler,
   BitfabOpenAITracingProcessor,
+  BitfabRivetIntegration,
   BitfabVercelAiHandler,
   DEFAULT_SERVICE_URL,
   DatasetsClient,