@openclawbrain/openclaw 0.1.1 → 0.1.3

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 RuntimeTurnBrainAttachmentPolicyV1, type ContextCompactionMode, type ContextContributionEvidenceStateV1, type CurrentProfileBrainStatusAnswerV1, 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 = ContextContributionEvidenceStateV1;
+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;
@@ -97,6 +245,7 @@ export interface OpenClawRuntimeTurnInput {
     maxContextBlocks?: number;
     mode?: RouteMode;
     runtimeHints?: readonly string[];
+    brainAttachmentPolicy?: RuntimeTurnBrainAttachmentPolicyV1 | null;
     compile?: RuntimeTurnCompileInput | null;
     delivery?: boolean | RuntimeTurnDeliveryInput | null;
     feedback?: readonly (RuntimeTurnFeedbackInput | null)[] | null;
@@ -130,6 +279,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 +468,426 @@ 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 declare const OPERATOR_API_CONTRACT_ID: "openclaw_operator_api.v1";
+export declare const SUPPORTED_OPERATOR_API_FAMILIES: readonly ["bootstrap_attach", "status", "export", "refresh", "promote", "rollback", "proof_observability"];
+export type SupportedOperatorApiFamily = (typeof SUPPORTED_OPERATOR_API_FAMILIES)[number];
+export type OperatorApiRouteScope = "cli" | "programmatic" | "proof_lane";
+export interface OperatorApiRouteDescriptor {
+    family: SupportedOperatorApiFamily;
+    scope: OperatorApiRouteScope;
+    packageName: string;
+    entrypoints: readonly string[];
+    summary: string;
+    notes: readonly string[];
+}
+export interface OperatorApiContractV1 {
+    contract: typeof OPERATOR_API_CONTRACT_ID;
+    runtimeOwner: "openclaw";
+    scope: "narrow_supported_operator_surface";
+    families: readonly SupportedOperatorApiFamily[];
+    routes: readonly OperatorApiRouteDescriptor[];
+    quarantinedSurface: readonly string[];
+}
+export declare const OPERATOR_API_CONTRACT_V1: {
+    readonly contract: "openclaw_operator_api.v1";
+    readonly runtimeOwner: "openclaw";
+    readonly scope: "narrow_supported_operator_surface";
+    readonly families: readonly ["bootstrap_attach", "status", "export", "refresh", "promote", "rollback", "proof_observability"];
+    readonly routes: readonly [{
+        readonly family: "bootstrap_attach";
+        readonly scope: "programmatic";
+        readonly packageName: "@openclawbrain/openclaw";
+        readonly entrypoints: readonly ["bootstrapRuntimeAttach", "describeAttachStatus"];
+        readonly summary: "Bootstrap the first attach pack and prove the initial handoff state without pretending live learning has already run.";
+        readonly notes: readonly ["Zero-event bootstrap is supported and stays explicit through awaiting_first_export.", "Attach serves only from activation's active slot after bootstrap completes."];
+    }, {
+        readonly family: "status";
+        readonly scope: "cli";
+        readonly packageName: "@openclawbrain/openclaw";
+        readonly entrypoints: readonly ["openclawbrain-ops status", "describeCurrentProfileBrainStatus"];
+        readonly summary: "Read the canonical current-profile brain-status object for the active Host/Profile/Brain/Attachment boundary.";
+        readonly notes: readonly ["Status is the first operator read path.", "describeCurrentProfileBrainStatus() freezes the supported Host/Profile/Brain/Attachment answer shape for the current profile.", "Use activation and export observability proof helpers when you need candidate/previous or export-freshness detail."];
+    }, {
+        readonly family: "export";
+        readonly scope: "programmatic";
+        readonly packageName: "@openclawbrain/openclaw";
+        readonly entrypoints: readonly ["buildNormalizedRuntimeEventExport", "writeRuntimeEventExportBundle", "loadRuntimeEventExportBundle"];
+        readonly summary: "Emit the deterministic learner handoff artifact explicitly instead of folding export into a larger implicit runtime loop.";
+        readonly notes: readonly ["Export is an off-hot-path operator handoff artifact, not proof of immediate active-pack mutation.", "Bundle roots and normalized payloads are both accepted downstream by observability surfaces."];
+    }, {
+        readonly family: "refresh";
+        readonly scope: "programmatic";
+        readonly packageName: "@openclawbrain/learner";
+        readonly entrypoints: readonly ["createAlwaysOnLearningRuntimeState", "advanceAlwaysOnLearningRuntime", "materializeAlwaysOnLearningCandidatePack"];
+        readonly summary: "Refresh candidate learning state explicitly through the learner boundary before any activation-pointer move happens.";
+        readonly notes: readonly ["Refresh is PG-only candidate-pack materialization in this repo.", "Refresh does not mutate the currently served active pack in place."];
+    }, {
+        readonly family: "promote";
+        readonly scope: "programmatic";
+        readonly packageName: "@openclawbrain/pack-format";
+        readonly entrypoints: readonly ["stageCandidatePack", "promoteCandidatePack"];
+        readonly summary: "Stage and promote activation-ready candidate packs through explicit pointer changes.";
+        readonly notes: readonly ["Promotion is the only path that changes which pack is served.", "Candidate and previous remain inspectable around the pointer move."];
+    }, {
+        readonly family: "rollback";
+        readonly scope: "cli";
+        readonly packageName: "@openclawbrain/openclaw";
+        readonly entrypoints: readonly ["openclawbrain-ops rollback", "rollbackRuntimeAttach", "formatOperatorRollbackReport"];
+        readonly summary: "Preview and apply the explicit active<-previous / active->candidate rollback move.";
+        readonly notes: readonly ["Rollback is blocked when the previous pointer is unavailable.", "Dry-run is the required first read path for safe operator rollback."];
+    }, {
+        readonly family: "proof_observability";
+        readonly scope: "programmatic";
+        readonly packageName: "@openclawbrain/openclaw";
+        readonly entrypoints: readonly ["describeAttachStatus", "describeKernelBrainBoundary"];
+        readonly summary: "Prove the local attach and kernel-vs-brain boundary from the shipped bridge surface.";
+        readonly notes: readonly ["Use these for repo-local or installed-package operator proof reads.", "These surfaces report the promoted artifact boundary, not full live runtime plasticity."];
+    }, {
+        readonly family: "proof_observability";
+        readonly scope: "programmatic";
+        readonly packageName: "@openclawbrain/pack-format";
+        readonly entrypoints: readonly ["describeActivationObservability"];
+        readonly summary: "Inspect activation health, freshness, route artifacts, rollback lineage, and slot readiness.";
+        readonly notes: readonly ["Activation observability is the ground truth for active/candidate/previous slot inspection."];
+    }, {
+        readonly family: "proof_observability";
+        readonly scope: "programmatic";
+        readonly packageName: "@openclawbrain/event-export";
+        readonly entrypoints: readonly ["describeNormalizedEventExportObservability"];
+        readonly summary: "Inspect supervision freshness and teacher freshness from the exported learner handoff artifact.";
+        readonly notes: readonly ["Export observability is local-to-export proof only."];
+    }, {
+        readonly family: "proof_observability";
+        readonly scope: "proof_lane";
+        readonly packageName: "workspace";
+        readonly entrypoints: readonly ["pnpm current-profile-lifecycle:smoke", "pnpm observability:smoke"];
+        readonly summary: "Run the repo-local proof lanes that derive operator truth from the canonical current-profile status object plus activation observability.";
+        readonly notes: readonly ["These lanes are proof machinery, not a second semver-stable API."];
+    }];
+    readonly quarantinedSurface: readonly ["openclawbrain-ops doctor was deleted; use the canonical current-profile status object plus proof helpers instead of a parallel troubleshooting surface.", "buildOperatorSurfaceReport / formatOperatorStatusReport / formatOperatorDoctorReport were historical parallel status surfaces and are not the supported operator API.", "runContinuousProductLoopTurn collapses export/refresh/promote into one proof helper and is not the supported operator API.", "runRecordedSessionReplay and recorded-session fixtures are proof helpers, not operator API.", "release scripts, root smoke plumbing, and workspace layout are proof-and-build machinery, not operator API.", "runRuntimeTurn is a runtime convenience wrapper and not the narrow operator export contract.", "createAsyncTeacherLiveLoop is supporting internals for refresh/teacher snapshots, not the narrow operator contract."];
+};
+export declare const OPENCLAW_OPERATOR_NOUNS_V1: readonly ["Host", "Profile", "Brain", "Attachment"];
+export declare const CURRENT_PROFILE_BRAIN_STATUS_CONTRACT: "current_profile_brain_status.v1";
+export declare const BRAIN_ATTACHMENT_POLICY_SEMANTICS_V1: {
+    readonly undeclared: "The Host has not declared whether the current Profile's Brain attachment policy is shared or dedicated; do not infer profile exclusivity from activation state alone.";
+    readonly dedicated: "The Host declares a dedicated Brain attachment policy: one Profile is intentionally attached to one Brain activation root, and operators may treat the served Brain state as profile-specific until the attachment changes.";
+    readonly shared: "The Host declares a shared Brain attachment policy: multiple Profiles may intentionally attach to the same Brain activation root, attribution must stay current-profile explicit, and operators must not treat later served context as profile-exclusive.";
+};
+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;
+    exportedAt: 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 CurrentProfileBrainStatusInput extends OperatorSurfaceInput {
+    brainAttachmentPolicy?: RuntimeTurnBrainAttachmentPolicyV1 | null;
+}
+export type CurrentProfileBrainStatusV1 = CurrentProfileBrainStatusAnswerV1;
+export declare function describeCurrentProfileBrainStatus(input: CurrentProfileBrainStatusInput): CurrentProfileBrainStatusV1;
+export declare function formatOperatorRollbackReport(result: RollbackRuntimeAttachResult): 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";