bitfab 0.61.2 → 0.61.4

package/dist/index.d.cts

@@ -22,6 +22,64 @@ type ApprovalFields = {
     approvedAt: string | null;
 };
 
+/** A node is identified by its workflow key and span name, never its display label. */
+interface ReplayNodeIdentity {
+    traceFunctionKey: string;
+    spanName: string;
+}
+/** Experimental, explicit policy for the TypeScript selective replay prototype. */
+interface SelectiveReplayOptions {
+    /** Subtrees that must execute: changed code and unchanged code with required effects. */
+    mustRun: ReplayNodeIdentity[];
+}
+interface SelectiveReplayNode extends ReplayNodeIdentity {
+    id: string;
+    parentId: string | null;
+    mustRun: boolean;
+    reusable: boolean;
+    reason: "root" | "must-run" | "ancestor" | "assertion" | "unresolved-must-run" | "eligible" | "not-reusable" | "missing-recording";
+    recording?: {
+        input: unknown[];
+        kwargs?: Record<string, unknown>;
+        output: unknown;
+    };
+}
+interface SelectiveReplayAssertion {
+    id: string;
+    target: null | {
+        kind: "output";
+    } | {
+        kind: "span";
+        name: string;
+        occurrence?: "first" | "last" | number;
+    };
+}
+interface SelectiveReplayPlan {
+    version: 4;
+    rootId: string;
+    options: SelectiveReplayOptions;
+    unresolvedMustRun: ReplayNodeIdentity[];
+    nodes: SelectiveReplayNode[];
+    assertions: SelectiveReplayAssertion[];
+}
+interface SelectiveReplayDecision extends ReplayNodeIdentity {
+    originalSpanId: string | null;
+    action: "run" | "mock" | "blocked";
+    reason: string;
+}
+/** Per-item execution evidence. A node not reached is not claimed as tested. */
+interface SelectiveReplayReport {
+    decisions: SelectiveReplayDecision[];
+    mustRunNotReached: ReplayNodeIdentity[];
+    unresolvedMustRun: ReplayNodeIdentity[];
+    /** Assertion IDs loaded for planning; these are not verdicts. */
+    assertionIds: string[];
+    /** Assertion IDs whose span target was absent/out of range in the recording. */
+    unresolvedAssertions: string[];
+    /** Assertion IDs whose requested span occurrence was not reached in this replay. */
+    assertionTargetsNotReached: string[];
+}
+
 declare class TraceCompletion {
     private readonly traces;
     private readonly closed;
@@ -193,6 +251,42 @@ interface MockOverride {
 /** Accepted shape for one mock override declaration. */
 type MockOverrideInput = MockOverride | MockOverrideResolver;
 
+declare class SelectiveReplayRuntime {
+    private readonly plan;
+    private readonly options;
+    private readonly nodes;
+    private readonly children;
+    private readonly runtimeParents;
+    private readonly consumed;
+    private readonly required;
+    private readonly requiredScopes;
+    private readonly recordings;
+    private readonly reached;
+    private readonly decisions;
+    private readonly assertionNames;
+    private readonly assertionScopes;
+    private readonly observedNames;
+    private readonly unresolvedAssertions;
+    private readonly fullTraceForAssertions;
+    private failure?;
+    constructor(plan: SelectiveReplayPlan, options: SelectiveReplayOptions);
+    enter(params: ReplayNodeIdentity & {
+        spanId: string;
+        parentSpanId: string | null;
+        inputs: unknown[];
+        safetyMock: boolean;
+        canReuseOutput: boolean;
+        reuseAllowed: boolean;
+    }): {
+        mock: false;
+    } | {
+        mock: true;
+        output: unknown;
+    };
+    assertNoSafetyConflict(): void;
+    report(): SelectiveReplayReport;
+}
+
 /**
  * Replay context propagation via AsyncLocalStorage.
  *
@@ -300,6 +394,7 @@ interface MockTree {
 }
 interface ReplayContext {
     experimentId: string;
+    selectiveReplay?: SelectiveReplayRuntime;
     traceId?: string;
     inputSourceSpanId?: string;
     /**
@@ -602,7 +697,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * Blocking call - creates an experiment and returns lightweight item references.
      */
-    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, judgeAssertions?: boolean): Promise<StartReplayResponse>;
+    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, judgeAssertions?: boolean, experimentalSelectiveReplay?: SelectiveReplayOptions): Promise<StartReplayResponse>;
     resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
@@ -638,6 +733,8 @@ declare class HttpClient {
      * Blocking call.
      */
     completeReplay(experimentId: string): Promise<CompleteReplayResponse>;
+    interruptReplay(experimentId: string): Promise<boolean>;
+    heartbeatReplay(experimentId: string): Promise<void>;
     getReseedSource(traceId: string): Promise<ReseedSourceResponse>;
     reseedTrace(traceId: string, runTraceId: string): Promise<ReseedTraceResponse>;
     /**
@@ -707,6 +804,7 @@ interface StartReplayResponse {
     experimentUrl: string;
     attempts?: number;
     items: Array<{
+        selectiveReplayPlan?: SelectiveReplayPlan;
         /** Bitfab trace ID of the original (historical) trace being replayed. */
         originalTraceId?: string;
         /** External span ID the recorded inputs were read from (the original root span). */
@@ -1855,6 +1953,14 @@ declare class OrganizationMembersClient {
     list(): Promise<OrganizationMember[]>;
 }
 
+type ReplayInterruptSignal = "SIGINT" | "SIGTERM";
+interface ReplayInterrupt {
+    experimentId: string;
+    experimentUrl: string;
+    signal: ReplayInterruptSignal;
+    markedInterrupted: boolean;
+}
+
 /**
  * Replay historical traces through a function and create an experiment.
  *
@@ -1897,6 +2003,15 @@ interface DbBranchOptions {
     warmupSql?: string;
 }
 interface ReplayOptions {
+    /**
+     * Experimental selective replay. Explicit required nodes
+     * always execute; eligible output-only nodes reuse JSON recordings only
+     * when runtime inputs match. Requires a compatible server, mock: "marked",
+     * and no mock overrides or resume. Does not infer changes from codeChangeFiles.
+     * The server reads active/inherited assertions and protects their scoped
+     * execution evidence. Coverage in item.selectiveReplay is not a verdict.
+     */
+    experimentalSelectiveReplay?: SelectiveReplayOptions;
     /**
      * Maximum number of traces to replay (1-5,000, default 5). Ignored when
      * `traceIds` is passed (with a warning), or when `datasetId` / `datasetIds`
@@ -2069,6 +2184,7 @@ interface ReplayOptions {
      * callback never crashes the run.
      */
     onExperimentStart?: (experiment: ReplayExperiment) => void;
+    onInterrupt?: (interrupt: ReplayInterrupt) => void;
     resume?: string;
     force?: boolean;
 }
@@ -2136,6 +2252,7 @@ interface ReplayItemFinishProgress {
 }
 /** See {@link ReplayItemFinishProgress.item}. Mirrors {@link ReplayItem}. */
 interface ReplayProgressItem {
+    selectiveReplay?: SelectiveReplayReport;
     /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
     traceId?: string | null;
     /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -2245,6 +2362,8 @@ interface AdaptContext {
  */
 type AdaptInputsFn = (inputs: unknown[], ctx: AdaptContext) => unknown[];
 interface ReplayItem<T> {
+    /** Decisions and changed-code coverage for experimental selective replay. */
+    selectiveReplay?: SelectiveReplayReport;
     /**
      * Server trace ID of the new replay trace this item produced. Written in by
      * `replay()` from the complete-replay response once the server has minted the
@@ -2934,6 +3053,15 @@ interface SpanOptions {
      * real child.
      */
     mockOnReplay?: boolean;
+    /**
+     * Experimental selective-replay eligibility, recorded with this span.
+     * Attests that the whole subtree is output-only with JSON value semantics:
+     * no hidden mutable reads, required effects, input mutations, or reliance
+     * on object identity. Include implementation/dependency changes in replay's
+     * mustRun. Both capture-time and current declarations must allow reuse.
+     * Does not affect ordinary replay or replace mockOnReplay safety protection.
+     */
+    replayReusable?: boolean;
     /** Optional experiment ID included on the span and on the trace it starts. */
     experimentId?: string;
     /**
@@ -3745,7 +3873,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.61.2";
+declare const __version__ = "0.61.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -3884,4 +4012,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 ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, 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 GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, 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 OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, 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 };
+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 AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, 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 GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, 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 OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, 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 SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, 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

@@ -22,6 +22,64 @@ type ApprovalFields = {
     approvedAt: string | null;
 };
 
+/** A node is identified by its workflow key and span name, never its display label. */
+interface ReplayNodeIdentity {
+    traceFunctionKey: string;
+    spanName: string;
+}
+/** Experimental, explicit policy for the TypeScript selective replay prototype. */
+interface SelectiveReplayOptions {
+    /** Subtrees that must execute: changed code and unchanged code with required effects. */
+    mustRun: ReplayNodeIdentity[];
+}
+interface SelectiveReplayNode extends ReplayNodeIdentity {
+    id: string;
+    parentId: string | null;
+    mustRun: boolean;
+    reusable: boolean;
+    reason: "root" | "must-run" | "ancestor" | "assertion" | "unresolved-must-run" | "eligible" | "not-reusable" | "missing-recording";
+    recording?: {
+        input: unknown[];
+        kwargs?: Record<string, unknown>;
+        output: unknown;
+    };
+}
+interface SelectiveReplayAssertion {
+    id: string;
+    target: null | {
+        kind: "output";
+    } | {
+        kind: "span";
+        name: string;
+        occurrence?: "first" | "last" | number;
+    };
+}
+interface SelectiveReplayPlan {
+    version: 4;
+    rootId: string;
+    options: SelectiveReplayOptions;
+    unresolvedMustRun: ReplayNodeIdentity[];
+    nodes: SelectiveReplayNode[];
+    assertions: SelectiveReplayAssertion[];
+}
+interface SelectiveReplayDecision extends ReplayNodeIdentity {
+    originalSpanId: string | null;
+    action: "run" | "mock" | "blocked";
+    reason: string;
+}
+/** Per-item execution evidence. A node not reached is not claimed as tested. */
+interface SelectiveReplayReport {
+    decisions: SelectiveReplayDecision[];
+    mustRunNotReached: ReplayNodeIdentity[];
+    unresolvedMustRun: ReplayNodeIdentity[];
+    /** Assertion IDs loaded for planning; these are not verdicts. */
+    assertionIds: string[];
+    /** Assertion IDs whose span target was absent/out of range in the recording. */
+    unresolvedAssertions: string[];
+    /** Assertion IDs whose requested span occurrence was not reached in this replay. */
+    assertionTargetsNotReached: string[];
+}
+
 declare class TraceCompletion {
     private readonly traces;
     private readonly closed;
@@ -193,6 +251,42 @@ interface MockOverride {
 /** Accepted shape for one mock override declaration. */
 type MockOverrideInput = MockOverride | MockOverrideResolver;
 
+declare class SelectiveReplayRuntime {
+    private readonly plan;
+    private readonly options;
+    private readonly nodes;
+    private readonly children;
+    private readonly runtimeParents;
+    private readonly consumed;
+    private readonly required;
+    private readonly requiredScopes;
+    private readonly recordings;
+    private readonly reached;
+    private readonly decisions;
+    private readonly assertionNames;
+    private readonly assertionScopes;
+    private readonly observedNames;
+    private readonly unresolvedAssertions;
+    private readonly fullTraceForAssertions;
+    private failure?;
+    constructor(plan: SelectiveReplayPlan, options: SelectiveReplayOptions);
+    enter(params: ReplayNodeIdentity & {
+        spanId: string;
+        parentSpanId: string | null;
+        inputs: unknown[];
+        safetyMock: boolean;
+        canReuseOutput: boolean;
+        reuseAllowed: boolean;
+    }): {
+        mock: false;
+    } | {
+        mock: true;
+        output: unknown;
+    };
+    assertNoSafetyConflict(): void;
+    report(): SelectiveReplayReport;
+}
+
 /**
  * Replay context propagation via AsyncLocalStorage.
  *
@@ -300,6 +394,7 @@ interface MockTree {
 }
 interface ReplayContext {
     experimentId: string;
+    selectiveReplay?: SelectiveReplayRuntime;
     traceId?: string;
     inputSourceSpanId?: string;
     /**
@@ -602,7 +697,7 @@ declare class HttpClient {
      * Start a replay session by fetching historical traces.
      * Blocking call - creates an experiment and returns lightweight item references.
      */
-    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, judgeAssertions?: boolean): Promise<StartReplayResponse>;
+    startReplay(traceFunctionKey: string, limit: number | undefined, traceIds?: string[], name?: string, codeChangeDescription?: string | null, codeChangeFiles?: CodeChangeFile[] | null, includeDbBranchLease?: boolean, experimentGroupId?: string, datasetIds?: string[], graderIds?: string[], dbBranchSettings?: DbBranchSettings, attempts?: number, includeOriginalMetadata?: boolean, onlyWithAssertions?: boolean, judgeAssertions?: boolean, experimentalSelectiveReplay?: SelectiveReplayOptions): Promise<StartReplayResponse>;
     resumeReplay(experimentId: string, traceFunctionKey: string, codeChangeFiles?: CodeChangeFile[] | null, force?: boolean): Promise<ResumeReplayResponse>;
     /**
      * Fetch an external span by ID.
@@ -638,6 +733,8 @@ declare class HttpClient {
      * Blocking call.
      */
     completeReplay(experimentId: string): Promise<CompleteReplayResponse>;
+    interruptReplay(experimentId: string): Promise<boolean>;
+    heartbeatReplay(experimentId: string): Promise<void>;
     getReseedSource(traceId: string): Promise<ReseedSourceResponse>;
     reseedTrace(traceId: string, runTraceId: string): Promise<ReseedTraceResponse>;
     /**
@@ -707,6 +804,7 @@ interface StartReplayResponse {
     experimentUrl: string;
     attempts?: number;
     items: Array<{
+        selectiveReplayPlan?: SelectiveReplayPlan;
         /** Bitfab trace ID of the original (historical) trace being replayed. */
         originalTraceId?: string;
         /** External span ID the recorded inputs were read from (the original root span). */
@@ -1855,6 +1953,14 @@ declare class OrganizationMembersClient {
     list(): Promise<OrganizationMember[]>;
 }
 
+type ReplayInterruptSignal = "SIGINT" | "SIGTERM";
+interface ReplayInterrupt {
+    experimentId: string;
+    experimentUrl: string;
+    signal: ReplayInterruptSignal;
+    markedInterrupted: boolean;
+}
+
 /**
  * Replay historical traces through a function and create an experiment.
  *
@@ -1897,6 +2003,15 @@ interface DbBranchOptions {
     warmupSql?: string;
 }
 interface ReplayOptions {
+    /**
+     * Experimental selective replay. Explicit required nodes
+     * always execute; eligible output-only nodes reuse JSON recordings only
+     * when runtime inputs match. Requires a compatible server, mock: "marked",
+     * and no mock overrides or resume. Does not infer changes from codeChangeFiles.
+     * The server reads active/inherited assertions and protects their scoped
+     * execution evidence. Coverage in item.selectiveReplay is not a verdict.
+     */
+    experimentalSelectiveReplay?: SelectiveReplayOptions;
     /**
      * Maximum number of traces to replay (1-5,000, default 5). Ignored when
      * `traceIds` is passed (with a warning), or when `datasetId` / `datasetIds`
@@ -2069,6 +2184,7 @@ interface ReplayOptions {
      * callback never crashes the run.
      */
     onExperimentStart?: (experiment: ReplayExperiment) => void;
+    onInterrupt?: (interrupt: ReplayInterrupt) => void;
     resume?: string;
     force?: boolean;
 }
@@ -2136,6 +2252,7 @@ interface ReplayItemFinishProgress {
 }
 /** See {@link ReplayItemFinishProgress.item}. Mirrors {@link ReplayItem}. */
 interface ReplayProgressItem {
+    selectiveReplay?: SelectiveReplayReport;
     /** Trace ID of the new replay trace (null during the run; the server id arrives at completion). */
     traceId?: string | null;
     /** Bitfab trace ID of the original (historical) trace being replayed. */
@@ -2245,6 +2362,8 @@ interface AdaptContext {
  */
 type AdaptInputsFn = (inputs: unknown[], ctx: AdaptContext) => unknown[];
 interface ReplayItem<T> {
+    /** Decisions and changed-code coverage for experimental selective replay. */
+    selectiveReplay?: SelectiveReplayReport;
     /**
      * Server trace ID of the new replay trace this item produced. Written in by
      * `replay()` from the complete-replay response once the server has minted the
@@ -2934,6 +3053,15 @@ interface SpanOptions {
      * real child.
      */
     mockOnReplay?: boolean;
+    /**
+     * Experimental selective-replay eligibility, recorded with this span.
+     * Attests that the whole subtree is output-only with JSON value semantics:
+     * no hidden mutable reads, required effects, input mutations, or reliance
+     * on object identity. Include implementation/dependency changes in replay's
+     * mustRun. Both capture-time and current declarations must allow reuse.
+     * Does not affect ordinary replay or replace mockOnReplay safety protection.
+     */
+    replayReusable?: boolean;
     /** Optional experiment ID included on the span and on the trace it starts. */
     experimentId?: string;
     /**
@@ -3745,7 +3873,7 @@ interface CommitRef {
 /**
  * SDK version from package.json (injected at build time)
  */
-declare const __version__ = "0.61.2";
+declare const __version__ = "0.61.4";
 
 /**
  * Constants for the Bitfab SDK.
@@ -3884,4 +4012,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 ApprovalFields, type ApprovalState, type Approver, type ArchiveAssertionsParams, AssertionCategoriesClient, type AssertionCategory, type AssertionCategorySummary, type AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, 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 GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, 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 OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, 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 };
+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 AssertionEvidenceParameter, type AssertionGeneration, AssertionGenerationError, type AssertionGenerationStatus, AssertionGenerationTimeoutError, type AssertionLabelEvidence, type AssertionVerdict, type Assignee, 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 GenerateAssertionsOptions, type GetGraderLabelsParams, type GraderLabel, type GraderLabelSource, type GraderRerun, GraderRerunError, type GraderRerunProgress, type GraderRerunResult, type GraderRerunStatus, GraderRerunTimeoutError, GradersClient, HttpClient, type HumanLabelOutcome, type HumanLabelUpdate, type Justification, type JustificationSpan, type LabelAction, type LabelConfidence, type LabelOutcome, type LabelSource, type LabelStatus, type LabelTarget, 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 OrganizationMember, OrganizationMembersClient, type ProviderDefinition, type RemoveDatasetGradersResult, type RemoveDatasetTracesResult, ReplayBranch, ReplayError, type ReplayExperiment, type ReplayInterrupt, type ReplayInterruptSignal, type ReplayItem, type ReplayItemFinishProgress, type ReplayItemStartProgress, type ReplayNodeIdentity, 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 SelectiveReplayDecision, type SelectiveReplayOptions, type SelectiveReplayReport, 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

@@ -35,8 +35,8 @@ import {
   getCurrentTrace,
   reseedFromRegistry,
   seedFromRegistry
-} from "./chunk-LUOCT4HG.js";
-import "./chunk-BMJNDIVA.js";
+} from "./chunk-XGRQMQ2R.js";
+import "./chunk-K4XCWQBC.js";
 import {
   BITFAB_PROGRESS_PREFIX,
   DbBranchReplayError,
@@ -44,7 +44,7 @@ import {
   ReplayError,
   reportReplayProgress,
   serializeReplayResult
-} from "./chunk-A4UVO6BQ.js";
+} from "./chunk-PSAEQ4OW.js";
 import {
   BitfabError,
   DEFAULT_SERVICE_URL,
@@ -52,7 +52,7 @@ import {
   MixedTracingError,
   __version__,
   flushTraces
-} from "./chunk-INA6W7OB.js";
+} from "./chunk-54EGXUZ3.js";
 import "./chunk-BAOIRE5T.js";
 export {
   AssertionCategoriesClient,