@openclawbrain/openclaw 0.1.0 → 0.1.2

package/dist/src/index.d.ts

@@ -1,5 +1,10 @@
-import { type ActivationPointerRecordV1, type FeedbackEventKind, type NormalizedEventExportV1, type RouteMode, type RuntimeCompileResponseV1 } from "@openclawbrain/contracts";
-import { type ActivationSlotInspection } from "@openclawbrain/pack-format";
+import { CONTRACT_IDS, type ArtifactManifestV1, type ActivationPointerRecordV1, type ActivationPointerSlot, type ContextCompactionMode, type FeedbackEventKind, type FeedbackEventV1, type KernelSurfaceValidationResultV1, type LearningBootProfile, type InteractionEventV1, type NormalizedEventExportV1, type RouteMode, type RuntimeCompileResponseV1, type RuntimeCompileTargetV1, type RuntimeGraphPlasticityStateV1, type RuntimePlasticitySourceV1, type SparseFeedbackPolicyV1, type TeacherSupervisionArtifactV1, type WorkspaceInjectionSurfaceV1 } from "@openclawbrain/contracts";
+import { type AdvanceAlwaysOnLearningRuntimeInput, type AlwaysOnLearningCadenceV1, type AlwaysOnLearningMaterializationJobV1, type AlwaysOnLearningRuntimePlanV1, type AlwaysOnLearningRuntimeStateV1 } from "@openclawbrain/learner";
+import { type ActivationInspection, type ActivationObservabilityReport, type ActivationSlotInspection, type InitHandoffState } from "@openclawbrain/pack-format";
+export declare const DEFAULT_ASYNC_TEACHER_QUEUE_CAPACITY = 8;
+declare const RECORDED_SESSION_TRACE_CONTRACT: "recorded_session_trace.v1";
+declare const RECORDED_SESSION_FIXTURE_CONTRACT: "recorded_session_replay_fixture.v1";
+declare const RECORDED_SESSION_BUNDLE_CONTRACT: "recorded_session_replay_bundle.v1";
 declare const RUNTIME_EVENT_EXPORT_BUNDLE_CONTRACT: "normalized_event_export_bundle.v1";
 export declare const RUNTIME_EVENT_EXPORT_BUNDLE_LAYOUT: {
     readonly manifest: "manifest.json";
@@ -35,7 +40,9 @@ export interface CompileRuntimeContextInput {
     message: string;
     agentId?: string;
     maxContextBlocks?: number;
+    maxContextChars?: number;
     mode?: RouteMode;
+    compactionMode?: ContextCompactionMode;
     runtimeHints?: readonly string[];
 }
 export interface ActiveCompileTarget {
@@ -46,20 +53,161 @@ export interface ActiveCompileTarget {
 export interface RuntimeCompileSuccess {
     ok: true;
     fallbackToStaticContext: false;
+    hardRequirementViolated: false;
     activationRoot: string;
     activePackId: string;
     packRootDir: string;
     compileResponse: RuntimeCompileResponseV1;
     brainContext: string;
 }
-export interface RuntimeCompileFailure {
+export interface RuntimeCompileFailOpenFailure {
     ok: false;
     fallbackToStaticContext: true;
+    hardRequirementViolated: false;
     activationRoot: string;
     error: string;
     brainContext: string;
 }
+export interface RuntimeCompileHardFailure {
+    ok: false;
+    fallbackToStaticContext: false;
+    hardRequirementViolated: true;
+    activationRoot: string;
+    error: string;
+    brainContext: string;
+}
+export type RuntimeCompileFailure = RuntimeCompileFailOpenFailure | RuntimeCompileHardFailure;
 export type RuntimeCompileResult = RuntimeCompileSuccess | RuntimeCompileFailure;
+export interface AttachStatusInput {
+    activationRoot: string;
+    compile?: false | Omit<CompileRuntimeContextInput, "activationRoot">;
+}
+export type ContextContributionEvidenceState = "route_fn_and_brain_context" | "brain_context_only" | "route_fn_only" | "stable_kernel_only" | "fail_open_static_context" | "hard_fail" | "unprobed";
+export interface ContextAttributionSummaryV1 {
+    selectedContextCount: number;
+    stableKernelBlockCount: number;
+    brainCompiledBlockCount: number;
+    stableKernelSources: string[];
+    brainCompiledSources: string[];
+    selectionTiers: string | null;
+    evidence: ContextContributionEvidenceState;
+    detail: string;
+}
+export interface AttachCompileStatusV1 {
+    ok: boolean;
+    fallbackToStaticContext: boolean;
+    hardRequirementViolated: boolean;
+    activePackId: string | null;
+    usedLearnedRouteFn: boolean | null;
+    routerIdentity: string | null;
+    initMode: string | null;
+    handoffState: string | null;
+    seedSources: string[];
+    contextAttribution: ContextAttributionSummaryV1;
+    notes: string[];
+    error: string | null;
+}
+export interface OpenClawCompileBoundaryV1 {
+    contract: typeof CONTRACT_IDS.runtimeCompile;
+    activationSlot: "active";
+    entrypoint: "compileRuntimeContext";
+    servedFromCandidateBeforePromotion: false;
+    learnedRouteEvidenceRequiredWhenManifestRequiresIt: true;
+}
+export interface OpenClawEventExportBoundaryV1 {
+    emittedContracts: readonly [typeof CONTRACT_IDS.interactionEvents, typeof CONTRACT_IDS.feedbackEvents];
+    entrypoint: "runRuntimeTurn";
+    bundleWriteOptional: true;
+    writeFailuresEraseSuccessfulCompile: false;
+    learningHandoffStaysOffHotPath: true;
+}
+export interface OpenClawActivePackBoundaryV1 {
+    servingSlot: "active";
+    inspectableSlots: readonly ActivationPointerSlot[];
+    candidateServedBeforePromotion: false;
+    previousSlotUsedForRollback: true;
+}
+export interface OpenClawPromotionBoundaryV1 {
+    candidateSlot: "candidate";
+    activeSlot: "active";
+    previousSlot: "previous";
+    requiresActivationReadyCandidate: true;
+    compileSeesCandidateOnlyAfterPromotion: true;
+    promotionHappensOffHotPath: true;
+}
+export interface OpenClawFailOpenSemanticsV1 {
+    missingActivePackFallsBackToStaticContext: true;
+    learnedRequiredRouteArtifactDriftHardFails: true;
+    hardFailuresDisableStaticFallback: true;
+    eventExportWriteFailurePreservesCompile: true;
+}
+export interface OpenClawLandingBoundariesV1 {
+    compileBoundary: OpenClawCompileBoundaryV1;
+    eventExportBoundary: OpenClawEventExportBoundaryV1;
+    activePackBoundary: OpenClawActivePackBoundaryV1;
+    promotionBoundary: OpenClawPromotionBoundaryV1;
+    failOpenSemantics: OpenClawFailOpenSemanticsV1;
+    runtimeResponsibilities: string[];
+    brainResponsibilities: string[];
+}
+export interface AttachStatusSnapshotV1 {
+    runtimeOwner: "openclaw";
+    activationRoot: string;
+    inspection: ActivationInspection;
+    activeObservability: ActivationObservabilityReport | null;
+    compile: AttachCompileStatusV1 | null;
+    landingBoundaries: OpenClawLandingBoundariesV1;
+    successSignals: string[];
+}
+export interface RollbackRuntimeAttachInput {
+    activationRoot: string;
+    updatedAt?: string;
+    dryRun?: boolean;
+}
+export interface RollbackRuntimeAttachResult {
+    runtimeOwner: "openclaw";
+    activationRoot: string;
+    updatedAt: string;
+    dryRun: boolean;
+    allowed: boolean;
+    findings: string[];
+    before: {
+        activePackId: string | null;
+        candidatePackId: string | null;
+        previousPackId: string | null;
+    };
+    after: {
+        activePackId: string | null;
+        candidatePackId: string | null;
+        previousPackId: string | null;
+    } | null;
+    restoredPackId: string | null;
+    parkedCandidatePackId: string | null;
+}
+export interface BootstrapRuntimeAttachInput {
+    activationRoot: string;
+    packRoot: string;
+    packLabel: string;
+    workspace: AdvanceAlwaysOnLearningRuntimeInput["workspace"];
+    normalizedEventExport?: NormalizedEventExportV1;
+    interactionEvents?: readonly InteractionEventV1[];
+    feedbackEvents?: readonly FeedbackEventV1[];
+    learnedRouting?: boolean;
+    builtAt?: string;
+    activatedAt?: string;
+    offlineArtifacts?: string[];
+    structuralOps?: Partial<ArtifactManifestV1["graphDynamics"]["structuralOps"]>;
+    sparseFeedback?: Partial<SparseFeedbackPolicyV1>;
+    compile?: false | Omit<CompileRuntimeContextInput, "activationRoot">;
+}
+export interface BootstrapRuntimeAttachResult {
+    runtimeOwner: "openclaw";
+    activationRoot: string;
+    packRoot: string;
+    packId: string;
+    normalizedEventExport: NormalizedEventExportV1;
+    status: AttachStatusSnapshotV1;
+}
 export interface RuntimeTurnCompileInput {
     createdAt?: string | null;
     sequence?: number | null;
@@ -130,6 +278,183 @@ export type RuntimeTurnResult = RuntimeCompileResult & {
     eventExport: RuntimeEventExportResult;
     warnings: string[];
 };
+export type TeacherLoopNoOpReason = "none" | "duplicate_export" | "queue_full" | "no_teacher_artifacts";
+export interface AsyncTeacherLiveLoopInput extends Pick<AdvanceAlwaysOnLearningRuntimeInput, "packLabel" | "workspace" | "learnedRouting" | "builtAt" | "offlineArtifacts" | "structuralOps" | "sparseFeedback" | "liveSliceSize" | "backfillSliceSize" | "cadence"> {
+    maxQueuedExports?: number;
+    staleAfterMs?: number;
+}
+export interface AsyncTeacherQueuedExportJobV1 {
+    jobId: string;
+    exportDigest: string;
+    observedAt: string;
+    normalizedEventExport: NormalizedEventExportV1;
+}
+export interface AsyncTeacherLiveLoopDiagnosticsV1 {
+    acceptedExportCount: number;
+    processedExportCount: number;
+    duplicateExportCount: number;
+    droppedExportCount: number;
+    emittedArtifactCount: number;
+    dedupedArtifactCount: number;
+    lastProcessedAt: string | null;
+    latestFreshness: TeacherSupervisionArtifactV1["freshness"]["status"] | "none";
+    lastNoOpReason: TeacherLoopNoOpReason;
+    notes: string[];
+}
+export interface AsyncTeacherLiveLoopSnapshotV1 {
+    runtimeOwner: "openclaw";
+    queue: {
+        capacity: number;
+        depth: number;
+        running: boolean;
+    };
+    teacher: {
+        artifactCount: number;
+        artifacts: TeacherSupervisionArtifactV1[];
+        latestFreshness: TeacherSupervisionArtifactV1["freshness"]["status"] | "none";
+    };
+    learner: {
+        state: AlwaysOnLearningRuntimeStateV1;
+        lastMaterialization: AlwaysOnLearningMaterializationJobV1 | null;
+    };
+    diagnostics: AsyncTeacherLiveLoopDiagnosticsV1;
+}
+export interface AsyncTeacherEnqueueResultV1 {
+    accepted: boolean;
+    exportDigest: string;
+    queueDepth: number;
+    notes: string[];
+    reason: Exclude<TeacherLoopNoOpReason, "none"> | null;
+}
+export interface CanonicalSupervisionFeedbackRecordV1 {
+    eventId: string;
+    kind: FeedbackEventKind;
+    sequence: number;
+    createdAt: string;
+    content: string;
+    relatedInteractionId: string | null;
+}
+export interface CanonicalSupervisionV1 {
+    runtimeOwner: "openclaw";
+    exportDigest: string;
+    supervisionDigest: string;
+    sessionId: string | null;
+    channel: string | null;
+    eventRange: Pick<NormalizedEventExportV1["range"], "start" | "end" | "count">;
+    sourceStreams: string[];
+    humanLabelCount: number;
+    selfLabelCount: number;
+    feedbackCounts: {
+        corrections: number;
+        teachings: number;
+        approvals: number;
+        suppressions: number;
+    };
+    compilePackIds: string[];
+    relatedInteractionIds: string[];
+    feedback: CanonicalSupervisionFeedbackRecordV1[];
+}
+export interface ContinuousProductLoopPackVersionV1 {
+    version: number;
+    packId: string;
+    routePolicy: RuntimeCompileTargetV1["routePolicy"];
+    routerIdentity: string | null;
+    workspaceSnapshot: string;
+    workspaceRevision: string | null;
+    eventRange: RuntimeCompileTargetV1["eventRange"];
+    eventExportDigest: string | null;
+    builtAt: string;
+}
+export interface ContinuousProductLoopStateV1 {
+    runtimeOwner: "openclaw";
+    activationRoot: string;
+    loopRoot: string;
+    interactionEvents: InteractionEventV1[];
+    feedbackEvents: FeedbackEventV1[];
+    learner: AlwaysOnLearningRuntimeStateV1;
+    runtimePlasticity: RuntimeGraphPlasticityStateV1 | null;
+    activePackVersion: number;
+    currentActivePack: ContinuousProductLoopPackVersionV1 | null;
+    candidatePack: ContinuousProductLoopPackVersionV1 | null;
+    packLineage: ContinuousProductLoopPackVersionV1[];
+    nextPackVersion: number;
+    promotionCount: number;
+    lastSupervision: CanonicalSupervisionV1 | null;
+}
+export interface ContinuousProductLoopLearningUpdateV1 {
+    warnings: string[];
+    supervisionDigest: string | null;
+    bridgeDigest: string | null;
+    selectedSliceIds: string[];
+    materializationJobId: string | null;
+    materializationReason: AlwaysOnLearningMaterializationJobV1["reason"] | null;
+    materializationLane: AlwaysOnLearningMaterializationJobV1["lane"] | null;
+    candidateRootDir: string | null;
+    candidatePack: ContinuousProductLoopPackVersionV1 | null;
+    runtimePlasticity: RuntimeGraphPlasticityStateV1 | null;
+    promotionAllowed: boolean;
+    promotionFindings: string[];
+    promoted: boolean;
+}
+export interface RunContinuousProductLoopTurnInput {
+    activationRoot: string;
+    loopRoot: string;
+    packLabel: string;
+    workspace: AdvanceAlwaysOnLearningRuntimeInput["workspace"];
+    turn: OpenClawRuntimeTurnInput;
+    state?: ContinuousProductLoopStateV1;
+    learnedRouting?: boolean;
+    failOpen?: boolean;
+    autoPromote?: boolean;
+    candidateBuiltAt?: string | null;
+    stageUpdatedAt?: string | null;
+    promoteUpdatedAt?: string | null;
+    offlineArtifacts?: string[];
+    structuralOps?: Partial<ArtifactManifestV1["graphDynamics"]["structuralOps"]>;
+    sparseFeedback?: Partial<SparseFeedbackPolicyV1>;
+    liveSliceSize?: number;
+    backfillSliceSize?: number;
+    cadence?: Partial<AlwaysOnLearningCadenceV1>;
+}
+export interface ContinuousProductLoopTurnResultV1 {
+    runtimeOwner: "openclaw";
+    compileActiveVersion: number;
+    compileActivePackId: string | null;
+    turn: RuntimeTurnResult;
+    supervision: CanonicalSupervisionV1 | null;
+    learning: ContinuousProductLoopLearningUpdateV1;
+    state: ContinuousProductLoopStateV1;
+}
+export declare function buildCanonicalSupervision(normalizedEventExport: NormalizedEventExportV1): CanonicalSupervisionV1;
+export declare function createContinuousProductLoopState(input: {
+    activationRoot: string;
+    loopRoot: string;
+}): ContinuousProductLoopStateV1;
+export declare class AsyncTeacherLiveLoop {
+    private readonly input;
+    private readonly queueCapacity;
+    private readonly staleAfterMs;
+    private readonly queuedExportDigests;
+    private readonly seenExportDigests;
+    private queue;
+    private drainPromise;
+    private interactionEvents;
+    private feedbackEvents;
+    private teacherArtifacts;
+    private learnerState;
+    private lastMaterialization;
+    private diagnostics;
+    constructor(input: AsyncTeacherLiveLoopInput);
+    enqueueNormalizedEventExport(normalizedEventExport: NormalizedEventExportV1, options?: {
+        observedAt?: string;
+    }): AsyncTeacherEnqueueResultV1;
+    flush(): Promise<AsyncTeacherLiveLoopSnapshotV1>;
+    snapshot(): AsyncTeacherLiveLoopSnapshotV1;
+    private ensureDrain;
+    private drain;
+    private refreshNotes;
+}
+export declare function createAsyncTeacherLiveLoop(input: AsyncTeacherLiveLoopInput): AsyncTeacherLiveLoop;
 export declare function buildRuntimeEventExportBundleManifest(input: {
     exportName: string;
     exportedAt: string;
@@ -142,7 +467,370 @@ export declare function classifyFeedbackKind(content: string): FeedbackEventKind
 export declare function formatPromptContext(compileResponse: RuntimeCompileResponseV1): string;
 export declare function resolveActivePackForCompile(activationRoot: string): ActiveCompileTarget;
 export declare function compileRuntimeContext(input: CompileRuntimeContextInput): RuntimeCompileResult;
+export declare function describeAttachStatus(input: AttachStatusInput): AttachStatusSnapshotV1;
+export declare function rollbackRuntimeAttach(input: RollbackRuntimeAttachInput): RollbackRuntimeAttachResult;
+export declare function bootstrapRuntimeAttach(input: BootstrapRuntimeAttachInput): BootstrapRuntimeAttachResult;
 export declare function buildNormalizedRuntimeEventExport(turn: OpenClawRuntimeTurnInput, compileResult: RuntimeCompileResult): NormalizedEventExportV1;
 export declare function writeRuntimeEventExportBundle(turn: OpenClawRuntimeTurnInput, normalizedEventExport: NormalizedEventExportV1): RuntimeEventExportNoWrite | RuntimeEventExportWriteSuccess;
 export declare function runRuntimeTurn(turn: OpenClawRuntimeTurnInput, options?: RunRuntimeTurnOptions): RuntimeTurnResult;
-export {};
+export declare function runContinuousProductLoopTurn(input: RunContinuousProductLoopTurnInput): ContinuousProductLoopTurnResultV1;
+export type RecordedSessionReplayMode = "no_brain" | "seed_pack" | "learned_replay";
+export interface RecordedSessionReplayWorkspaceV1 {
+    workspaceId: string;
+    snapshotId: string;
+    capturedAt: string;
+    rootDir: string;
+    branch?: string;
+    revision: string;
+    labels?: string[];
+}
+export interface RecordedSessionSeedCueV1 {
+    cueId: string;
+    createdAt: string;
+    content: string;
+    kind?: FeedbackEventKind;
+}
+export interface RecordedSessionTraceFeedbackV1 {
+    createdAt: string;
+    content: string;
+    kind?: FeedbackEventKind | null;
+}
+export interface RecordedSessionTraceTurnV1 {
+    turnId?: string;
+    createdAt: string;
+    deliveredAt?: string | null;
+    userMessage: string;
+    runtimeHints?: readonly string[];
+    feedback?: readonly RecordedSessionTraceFeedbackV1[];
+    expectedContextPhrases: readonly string[];
+    minimumPhraseHits?: number;
+}
+export interface RecordedSessionTraceV1 {
+    contract: typeof RECORDED_SESSION_TRACE_CONTRACT;
+    traceId: string;
+    source: "sanitized_recorded_session";
+    recordedAt: string;
+    bundleBuiltAt: string;
+    agentId?: string | null;
+    sessionId: string;
+    channel: string;
+    sourceStream: string;
+    privacy: {
+        sanitized: true;
+        notes: string[];
+    };
+    workspace: RecordedSessionReplayWorkspaceV1;
+    seedBuiltAt: string;
+    seedActivatedAt: string;
+    seedCues: readonly RecordedSessionSeedCueV1[];
+    turns: readonly RecordedSessionTraceTurnV1[];
+}
+export interface RecordedSessionReplayTurnFixtureV1 {
+    turnId: string;
+    turn: OpenClawRuntimeTurnInput;
+    expectedContextPhrases: string[];
+    minimumPhraseHits: number;
+}
+export interface RecordedSessionReplayFixtureV1 {
+    contract: typeof RECORDED_SESSION_FIXTURE_CONTRACT;
+    traceId: string;
+    source: RecordedSessionTraceV1["source"];
+    recordedAt: string;
+    bundleBuiltAt: string;
+    traceHash: string;
+    fixtureHash: string;
+    privacy: RecordedSessionTraceV1["privacy"];
+    workspace: RecordedSessionReplayWorkspaceV1;
+    seedBuiltAt: string;
+    seedActivatedAt: string;
+    seedExport: NormalizedEventExportV1;
+    turns: RecordedSessionReplayTurnFixtureV1[];
+}
+export interface RecordedSessionReplayTurnReportV1 {
+    turnId: string;
+    compileOk: boolean;
+    fallbackToStaticContext: boolean;
+    hardRequirementViolated: boolean;
+    activePackId: string | null;
+    usedLearnedRouteFn: boolean;
+    routerIdentity: string | null;
+    selectionDigest: string | null;
+    selectedContextIds: string[];
+    selectedContextTexts: string[];
+    eventExportDigest: string | null;
+    expectedContextPhrases: string[];
+    minimumPhraseHits: number;
+    phraseHits: string[];
+    missedPhrases: string[];
+    qualityScore: number;
+    compileActiveVersion: number | null;
+    promoted: boolean;
+    warnings: string[];
+}
+export interface RecordedSessionReplayModeSummaryV1 {
+    mode: RecordedSessionReplayMode;
+    qualityScore: number;
+    compileOkCount: number;
+    phraseHitCount: number;
+    phraseCount: number;
+    usedLearnedRouteTurnCount: number;
+    promotionCount: number;
+    packIds: string[];
+    scoreHash: string;
+}
+export interface RecordedSessionReplayModeReportV1 {
+    mode: RecordedSessionReplayMode;
+    summary: RecordedSessionReplayModeSummaryV1;
+    turns: RecordedSessionReplayTurnReportV1[];
+}
+export interface RecordedSessionReplayBundleV1 {
+    contract: typeof RECORDED_SESSION_BUNDLE_CONTRACT;
+    traceId: string;
+    source: RecordedSessionReplayFixtureV1["source"];
+    recordedAt: string;
+    generatedAt: string;
+    traceHash: string;
+    fixtureHash: string;
+    scoreHash: string;
+    bundleHash: string;
+    privacy: RecordedSessionReplayFixtureV1["privacy"];
+    modes: RecordedSessionReplayModeReportV1[];
+    summary: {
+        winnerMode: RecordedSessionReplayMode | null;
+        ranking: Array<{
+            mode: RecordedSessionReplayMode;
+            qualityScore: number;
+        }>;
+    };
+}
+export interface RecordedSessionReplayRescoreReportV1 {
+    scoreHash: string;
+    modes: Array<{
+        mode: RecordedSessionReplayMode;
+        qualityScore: number;
+        scoreHash: string;
+    }>;
+}
+export interface RecordedSessionReplayBundleHashVerificationV1 {
+    bundleHashMatches: boolean;
+    scoreHashMatches: boolean;
+}
+export declare function buildRecordedSessionReplayFixture(trace: RecordedSessionTraceV1): RecordedSessionReplayFixtureV1;
+export declare function runRecordedSessionReplay(rootDir: string, fixture: RecordedSessionReplayFixtureV1): RecordedSessionReplayBundleV1;
+export declare function rescoreRecordedSessionReplayBundle(bundle: RecordedSessionReplayBundleV1): RecordedSessionReplayRescoreReportV1;
+export declare function verifyRecordedSessionReplayBundleHashes(bundle: RecordedSessionReplayBundleV1): RecordedSessionReplayBundleHashVerificationV1;
+export type OperatorSurfaceStatus = "ok" | "warn" | "fail";
+export type OperatorFindingSeverity = "pass" | "warn" | "fail";
+export type OperatorLastPromotionConfidence = "proven_from_previous_pointer" | "unknown_from_local_pointers" | "no_active_pack";
+export type OperatorBrainState = InitHandoffState | "no_active_pack";
+export type OperatorServePathState = "serving_active_pack" | "fail_open_static_context" | "hard_fail" | "unprobed";
+export interface OperatorSurfaceInput {
+    activationRoot: string;
+    updatedAt?: string | null;
+    eventExportPath?: string | null;
+    teacherSnapshotPath?: string | null;
+}
+export interface OperatorSurfaceSlotSummary {
+    slot: ActivationPointerSlot;
+    packId: string;
+    activationReady: boolean;
+    routePolicy: RuntimeCompileTargetV1["routePolicy"];
+    routerIdentity: string | null;
+    workspaceSnapshot: string;
+    workspaceRevision: string | null;
+    eventRange: RuntimeCompileTargetV1["eventRange"];
+    eventExportDigest: string | null;
+    builtAt: string;
+    updatedAt: string | null;
+    findings: string[];
+}
+export interface OperatorLastPromotionSummary {
+    known: boolean;
+    at: string | null;
+    confidence: OperatorLastPromotionConfidence;
+    note: string;
+}
+export interface OperatorBrainStateSummary {
+    state: OperatorBrainState;
+    initMode: LearningBootProfile | null;
+    runtimePlasticitySource: RuntimePlasticitySourceV1 | null;
+    seedStateVisible: boolean;
+    seedBlockCount: number;
+    activePackId: string | null;
+    activeWorkspaceSnapshot: string | null;
+    activeEventExportDigest: string | null;
+    detail: string;
+}
+export interface OperatorServePathSummary {
+    state: OperatorServePathState;
+    fallbackToStaticContext: boolean;
+    hardRequirementViolated: boolean;
+    activePackId: string | null;
+    usedLearnedRouteFn: boolean | null;
+    routerIdentity: string | null;
+    selectionMode: string | null;
+    refreshStatus: string | null;
+    freshnessChecksum: string | null;
+    contextAttribution: ContextAttributionSummaryV1;
+    error: string | null;
+}
+export interface OperatorDoctorFinding {
+    severity: OperatorFindingSeverity;
+    code: string;
+    summary: string;
+    detail: string;
+}
+export interface OperatorSupervisionSummary {
+    available: boolean;
+    sourcePath: string | null;
+    sourceKind: "bundle_root" | "payload" | "missing";
+    exportDigest: string | null;
+    flowing: boolean | null;
+    sourceCount: number;
+    freshestSourceStream: string | null;
+    freshestCreatedAt: string | null;
+    freshestKind: string | null;
+    humanLabelCount: number | null;
+    sources: string[];
+    detail: string;
+}
+export interface OperatorTeacherLoopSummary {
+    available: boolean;
+    sourcePath: string | null;
+    lastNoOpReason: TeacherLoopNoOpReason | "unavailable";
+    latestFreshness: AsyncTeacherLiveLoopDiagnosticsV1["latestFreshness"] | "unavailable";
+    lastProcessedAt: string | null;
+    queueDepth: number | null;
+    queueCapacity: number | null;
+    running: boolean | null;
+    lastMaterializedPackId: string | null;
+    notes: string[];
+    detail: string;
+}
+export interface OperatorLearningSummary {
+    available: boolean;
+    sourcePath: string | null;
+    bootstrapped: boolean | null;
+    mode: AlwaysOnLearningRuntimePlanV1["mode"] | "unavailable";
+    nextPriorityLane: AlwaysOnLearningRuntimePlanV1["nextPriorityLane"] | "unavailable";
+    pendingLive: number | null;
+    pendingBackfill: number | null;
+    pendingTotal: number | null;
+    freshLivePriority: boolean | null;
+    learnedRange: RuntimeCompileTargetV1["eventRange"] | null;
+    materializationCount: number | null;
+    lastMaterializedAt: string | null;
+    lastMaterializationReason: AlwaysOnLearningMaterializationJobV1["reason"] | null;
+    lastMaterializationLane: AlwaysOnLearningMaterializationJobV1["lane"] | null;
+    lastMaterializationPriority: AlwaysOnLearningMaterializationJobV1["priority"] | null;
+    lastMaterializedPackId: string | null;
+    detail: string;
+}
+export interface OperatorSurfaceReport {
+    generatedAt: string;
+    activationRoot: string;
+    status: OperatorSurfaceStatus;
+    active: OperatorSurfaceSlotSummary | null;
+    candidate: OperatorSurfaceSlotSummary | null;
+    previous: OperatorSurfaceSlotSummary | null;
+    freshness: {
+        activeBehindPromotionReadyCandidate: boolean;
+        candidateAheadBy: string[];
+    };
+    brain: OperatorBrainStateSummary;
+    learnedRouting: {
+        required: boolean;
+        available: boolean;
+        routerIdentity: string | null;
+        routeFnVersion: string | null;
+        trainingMethod: string | null;
+        routerTrainedAt: string | null;
+        objective: string | null;
+        pgProfile: ActivationObservabilityReport["learnedRouteFn"]["pgProfile"];
+        objectiveChecksum: string | null;
+        updateMechanism: string | null;
+        updateVersion: string | null;
+        updateCount: number | null;
+        supervisionCount: number | null;
+        collectedLabelsTotal: number | null;
+        freshnessChecksum: string | null;
+        handoffState: InitHandoffState;
+        initMode: LearningBootProfile | null;
+        seedStateVisible: boolean;
+    };
+    servePath: OperatorServePathSummary;
+    promotion: {
+        allowed: boolean;
+        findings: string[];
+        lastPromotion: OperatorLastPromotionSummary;
+        activeUpdatedAt: string | null;
+        candidateUpdatedAt: string | null;
+        previousUpdatedAt: string | null;
+    };
+    rollback: {
+        allowed: boolean;
+        findings: string[];
+        previousPackId: string | null;
+        state: "ready" | "blocked" | "unknown";
+    };
+    supervision: OperatorSupervisionSummary;
+    learning: OperatorLearningSummary;
+    teacherLoop: OperatorTeacherLoopSummary;
+    findings: OperatorDoctorFinding[];
+}
+export declare function buildOperatorSurfaceReport(input: OperatorSurfaceInput): OperatorSurfaceReport;
+export declare function formatOperatorRollbackReport(result: RollbackRuntimeAttachResult): string;
+export declare function formatOperatorStatusReport(report: OperatorSurfaceReport): string;
+export declare function formatOperatorDoctorReport(report: OperatorSurfaceReport): string;
+/**
+ * A per-turn summary of what was kernel-injected vs brain-compiled in a given
+ * compile response. Useful for operator observability and debugging.
+ *
+ * "Kernel" content is whatever the operator injected directly in the system
+ * prompt — this function cannot observe it, only describe the brain side.
+ * The `kernelSurface` field is present only when the caller supplies a surface
+ * descriptor (from `WorkspaceInjectionSurfaceV1`) alongside the compile
+ * response; otherwise it is null.
+ */
+export interface KernelBrainBoundaryDescriptionV1 {
+    /**
+     * Summary of what the brain compiler contributed to this turn.
+     */
+    brain: {
+        packId: string;
+        mode: "learned" | "heuristic";
+        selectedBlockCount: number;
+        /** Roles of the selected blocks, deduplicated. */
+        selectedRoles: string[];
+        /** Whether the learned route_fn ran (true means learned routing was used). */
+        usedLearnedRouteFn: boolean;
+        /** Whether context was compacted due to char budget pressure. */
+        compactionApplied: boolean;
+    };
+    /**
+     * Validation result for the operator-supplied kernel surface descriptor.
+     * Null when no surface descriptor was supplied.
+     */
+    kernelValidation: KernelSurfaceValidationResultV1 | null;
+    /**
+     * Advisory: based on the compile diagnostics, is the brain context likely
+     * covering the query well, or should the operator investigate pack freshness?
+     *
+     * - `"likely_covered"` — learned routing ran and found token-matched blocks.
+     * - `"partial"` — some token matches, but mode was heuristic or routing gap.
+     * - `"likely_gap"` — no token matches or heuristic-only; pack may need refresh.
+     */
+    brainCoverageAdvisory: "likely_covered" | "partial" | "likely_gap";
+}
+/**
+ * Describes the kernel/brain boundary for a single compile response.
+ *
+ * Combines:
+ * - Brain context summary (from the compile response diagnostics)
+ * - Kernel surface validation (if a surface descriptor is supplied)
+ * - A coverage advisory based on routing signals
+ *
+ * See `docs/kernel-brain-boundary.md` for the full decision framework.
+ */
+export declare function describeKernelBrainBoundary(compileResponse: RuntimeCompileResponseV1, surface?: WorkspaceInjectionSurfaceV1): KernelBrainBoundaryDescriptionV1;
+export type { BrainEligibleContentKind, KernelContentKind, KernelSurfaceValidationResultV1, WorkspaceInjectionSurfaceV1 } from "@openclawbrain/contracts";