@openclawbrain/openclaw 0.1.9 → 0.1.11

package/dist/src/index.js

@@ -910,6 +910,216 @@ function classifyCompileFailure(error, activationRoot) {
     }
     return failOpenCompileResult(error, resolvedActivationRoot);
 }
+function uniqueNotes(notes) {
+    return [...new Set(notes.filter((note) => note.length > 0))];
+}
+function clampInteger(value, minimum, maximum) {
+    return Math.min(maximum, Math.max(minimum, Math.round(value)));
+}
+export function deriveEmpiricalStructuralBudget(input) {
+    const requestedStrategy = input.requestedStrategy ?? "fixed_v1";
+    const defaultMaxContextBlocks = input.defaultMaxContextBlocks ?? 4;
+    const minimumMaxContextBlocks = input.minimumMaxContextBlocks ?? 2;
+    const maximumMaxContextBlocks = input.maximumMaxContextBlocks ?? 6;
+    if (input.requestedMaxContextBlocks !== undefined) {
+        const maxContextBlocks = clampInteger(input.requestedMaxContextBlocks, 0, Number.MAX_SAFE_INTEGER);
+        return {
+            requestedStrategy,
+            effectiveStrategy: requestedStrategy,
+            maxContextBlocks,
+            defaultMaxContextBlocks,
+            evidence: { split: 0, merge: 0, prune: 0, connect: 0 },
+            evidenceTotal: 0,
+            tendencies: { split: 0, merge: 0, prune: 0, connect: 0 },
+            notes: [
+                `requested_budget_strategy=${requestedStrategy}`,
+                `requested_max_context_blocks=${maxContextBlocks}`,
+                `resolved_budget_strategy=${requestedStrategy}`,
+                `resolved_max_context_blocks=${maxContextBlocks}`,
+                "structural_budget_source=caller_override"
+            ]
+        };
+    }
+    if (requestedStrategy !== "empirical_v1") {
+        return {
+            requestedStrategy,
+            effectiveStrategy: requestedStrategy,
+            maxContextBlocks: defaultMaxContextBlocks,
+            defaultMaxContextBlocks,
+            evidence: { split: 0, merge: 0, prune: 0, connect: 0 },
+            evidenceTotal: 0,
+            tendencies: { split: 0, merge: 0, prune: 0, connect: 0 },
+            notes: [
+                `requested_budget_strategy=${requestedStrategy}`,
+                `resolved_budget_strategy=${requestedStrategy}`,
+                `resolved_max_context_blocks=${defaultMaxContextBlocks}`,
+                `structural_budget_source=${requestedStrategy === "fixed_v1" ? "fixed_default" : "fixed_fallback"}`
+            ]
+        };
+    }
+    const evidence = {
+        split: Math.max(0, input.evolution?.structuralOps.split ?? 0),
+        merge: Math.max(0, input.evolution?.structuralOps.merge ?? 0),
+        prune: Math.max(0, Math.max(input.evolution?.structuralOps.prune ?? 0, input.evolution?.prunedBlockIds.length ?? 0)),
+        connect: Math.max(0, input.evolution?.structuralOps.connect ?? 0)
+    };
+    const evidenceTotal = evidence.split + evidence.merge + evidence.prune + evidence.connect;
+    if (evidenceTotal === 0) {
+        return {
+            requestedStrategy,
+            effectiveStrategy: "fixed_v1",
+            maxContextBlocks: defaultMaxContextBlocks,
+            defaultMaxContextBlocks,
+            evidence,
+            evidenceTotal,
+            tendencies: { split: 0, merge: 0, prune: 0, connect: 0 },
+            notes: [
+                `requested_budget_strategy=${requestedStrategy}`,
+                "resolved_budget_strategy=fixed_v1",
+                `resolved_max_context_blocks=${defaultMaxContextBlocks}`,
+                "structural_budget_source=no_evidence_fallback"
+            ]
+        };
+    }
+    const tendencies = {
+        split: evidence.split / evidenceTotal,
+        merge: evidence.merge / evidenceTotal,
+        prune: evidence.prune / evidenceTotal,
+        connect: evidence.connect / evidenceTotal
+    };
+    const expansionPressure = tendencies.split + tendencies.connect;
+    const contractionPressure = tendencies.merge + tendencies.prune;
+    const directionalPressure = expansionPressure - contractionPressure;
+    const maxContextBlocks = clampInteger(defaultMaxContextBlocks + directionalPressure * 2, minimumMaxContextBlocks, maximumMaxContextBlocks);
+    return {
+        requestedStrategy,
+        effectiveStrategy: requestedStrategy,
+        maxContextBlocks,
+        defaultMaxContextBlocks,
+        evidence,
+        evidenceTotal,
+        tendencies,
+        notes: [
+            `requested_budget_strategy=${requestedStrategy}`,
+            `resolved_budget_strategy=${requestedStrategy}`,
+            `resolved_max_context_blocks=${maxContextBlocks}`,
+            "structural_budget_source=graph_evolution_empirical_v1",
+            `structural_budget_evidence=split:${evidence.split},merge:${evidence.merge},prune:${evidence.prune},connect:${evidence.connect},total:${evidenceTotal}`,
+            `structural_budget_tendencies=split:${tendencies.split.toFixed(4)},merge:${tendencies.merge.toFixed(4)},prune:${tendencies.prune.toFixed(4)},connect:${tendencies.connect.toFixed(4)}`,
+            `structural_budget_pressures=expand:${expansionPressure.toFixed(4)},contract:${contractionPressure.toFixed(4)},directional:${directionalPressure.toFixed(4)}`
+        ]
+    };
+}
+export function deriveEmpiricalStructuralBudgetFromCompileSignals(input) {
+    const requestedStrategy = input.requestedStrategy ?? "fixed_v1";
+    const defaultMaxContextBlocks = input.defaultMaxContextBlocks ?? 4;
+    const minimumMaxContextBlocks = input.minimumMaxContextBlocks ?? 2;
+    const maximumMaxContextBlocks = input.maximumMaxContextBlocks ?? 6;
+    if (input.requestedMaxContextBlocks !== undefined) {
+        const maxContextBlocks = clampInteger(input.requestedMaxContextBlocks, 0, Number.MAX_SAFE_INTEGER);
+        return {
+            requestedStrategy,
+            effectiveStrategy: requestedStrategy,
+            maxContextBlocks,
+            defaultMaxContextBlocks,
+            evidence: { split: 0, merge: 0, prune: 0, connect: 0 },
+            evidenceTotal: 0,
+            tendencies: { split: 0, merge: 0, prune: 0, connect: 0 },
+            notes: [
+                `requested_budget_strategy=${requestedStrategy}`,
+                `requested_max_context_blocks=${maxContextBlocks}`,
+                `resolved_budget_strategy=${requestedStrategy}`,
+                `resolved_max_context_blocks=${maxContextBlocks}`,
+                "structural_budget_source=caller_override"
+            ]
+        };
+    }
+    if (requestedStrategy !== "empirical_v1") {
+        return {
+            requestedStrategy,
+            effectiveStrategy: requestedStrategy,
+            maxContextBlocks: defaultMaxContextBlocks,
+            defaultMaxContextBlocks,
+            evidence: { split: 0, merge: 0, prune: 0, connect: 0 },
+            evidenceTotal: 0,
+            tendencies: { split: 0, merge: 0, prune: 0, connect: 0 },
+            notes: [
+                `requested_budget_strategy=${requestedStrategy}`,
+                `resolved_budget_strategy=${requestedStrategy}`,
+                `resolved_max_context_blocks=${defaultMaxContextBlocks}`,
+                `structural_budget_source=${requestedStrategy === "fixed_v1" ? "fixed_default" : "fixed_fallback"}`
+            ]
+        };
+    }
+    const compileEvidence = {
+        expansionCandidates: Math.max(0, (input.structuralSignals?.matchedCandidateCount ?? 0) - (input.structuralSignals?.selectedMatchedCount ?? 0)),
+        traversalActivations: Math.max(0, input.structuralSignals?.traversalActivatedCount ?? 0),
+        overlapPruned: Math.max(0, input.structuralSignals?.overlapPrunedCount ?? 0)
+    };
+    const evidence = {
+        split: compileEvidence.expansionCandidates,
+        merge: 0,
+        prune: compileEvidence.overlapPruned,
+        connect: compileEvidence.traversalActivations
+    };
+    const evidenceTotal = evidence.split + evidence.merge + evidence.prune + evidence.connect;
+    if (evidenceTotal === 0) {
+        return {
+            requestedStrategy,
+            effectiveStrategy: "fixed_v1",
+            maxContextBlocks: defaultMaxContextBlocks,
+            defaultMaxContextBlocks,
+            evidence,
+            evidenceTotal,
+            tendencies: { split: 0, merge: 0, prune: 0, connect: 0 },
+            notes: [
+                `requested_budget_strategy=${requestedStrategy}`,
+                "resolved_budget_strategy=fixed_v1",
+                `resolved_max_context_blocks=${defaultMaxContextBlocks}`,
+                "structural_budget_source=no_compile_signal_evidence_fallback"
+            ]
+        };
+    }
+    const tendencies = {
+        split: evidence.split / evidenceTotal,
+        merge: 0,
+        prune: evidence.prune / evidenceTotal,
+        connect: evidence.connect / evidenceTotal
+    };
+    const expansionPressure = tendencies.split + tendencies.connect;
+    const contractionPressure = tendencies.prune;
+    const directionalPressure = expansionPressure - contractionPressure;
+    const maxContextBlocks = clampInteger(defaultMaxContextBlocks + directionalPressure * 2, minimumMaxContextBlocks, maximumMaxContextBlocks);
+    return {
+        requestedStrategy,
+        effectiveStrategy: requestedStrategy,
+        maxContextBlocks,
+        defaultMaxContextBlocks,
+        evidence,
+        evidenceTotal,
+        tendencies,
+        notes: [
+            `requested_budget_strategy=${requestedStrategy}`,
+            `resolved_budget_strategy=${requestedStrategy}`,
+            `resolved_max_context_blocks=${maxContextBlocks}`,
+            "structural_budget_source=compile_structural_signals_empirical_v1",
+            `structural_budget_compile_evidence=matched_unselected:${compileEvidence.expansionCandidates},traversal:${compileEvidence.traversalActivations},overlap_pruned:${compileEvidence.overlapPruned},total:${evidenceTotal}`,
+            `structural_budget_tendencies=split:${tendencies.split.toFixed(4)},merge:${tendencies.merge.toFixed(4)},prune:${tendencies.prune.toFixed(4)},connect:${tendencies.connect.toFixed(4)}`,
+            `structural_budget_pressures=expand:${expansionPressure.toFixed(4)},contract:${contractionPressure.toFixed(4)},directional:${directionalPressure.toFixed(4)}`
+        ]
+    };
+}
+function resolveCompileBudget(target, input) {
+    const pack = loadPackFromActivation(target.activationRoot, "active");
+    return deriveEmpiricalStructuralBudget({
+        requestedStrategy: input.budgetStrategy ?? "empirical_v1",
+        ...(input.maxContextBlocks !== undefined ? { requestedMaxContextBlocks: input.maxContextBlocks } : {}),
+        ...(pack?.graph.evolution !== undefined ? { evolution: pack.graph.evolution } : {}),
+        defaultMaxContextBlocks: 4,
+        minimumMaxContextBlocks: 2,
+        maximumMaxContextBlocks: 6
+    });
+}
 export function resolveActivePackForCompile(activationRoot) {
     const resolvedActivationRoot = path.resolve(normalizeNonEmptyString(activationRoot, "activationRoot"));
     const inspection = inspectActivationState(resolvedActivationRoot);
@@ -932,11 +1142,12 @@ export function compileRuntimeContext(input) {
     const runtimeHints = normalizeRuntimeHints(input.runtimeHints);
     try {
         const target = resolveActivePackForCompile(activationRoot);
+        const resolvedBudget = resolveCompileBudget(target, input);
         const compile = compileRuntimeFromActivation(activationRoot, {
             contract: CONTRACT_IDS.runtimeCompile,
             agentId,
             userMessage: normalizeNonEmptyString(input.message, "message"),
-            maxContextBlocks: normalizeNonNegativeInteger(input.maxContextBlocks, "maxContextBlocks", 4),
+            maxContextBlocks: resolvedBudget.maxContextBlocks,
             ...(input.maxContextChars !== undefined
                 ? { maxContextChars: normalizeNonNegativeInteger(input.maxContextChars, "maxContextChars", input.maxContextChars) }
                 : {}),
@@ -949,7 +1160,7 @@ export function compileRuntimeContext(input) {
             ...compile.response,
             diagnostics: {
                 ...compile.response.diagnostics,
-                notes: [...compile.response.diagnostics.notes, "OpenClaw remains the runtime owner"]
+                notes: uniqueNotes([...compile.response.diagnostics.notes, ...resolvedBudget.notes, "OpenClaw remains the runtime owner"])
             }
         };
         return {
@@ -1147,6 +1358,7 @@ function buildAttachStatusCompileInput(activationRoot, compile) {
         agentId: normalizeOptionalString(compile?.agentId) ?? `${DEFAULT_AGENT_ID}-attach-status`,
         message: normalizeOptionalString(compile?.message) ?? DEFAULT_ATTACH_STATUS_MESSAGE,
         ...(compile?.maxContextBlocks !== undefined ? { maxContextBlocks: compile.maxContextBlocks } : {}),
+        ...(compile?.budgetStrategy !== undefined ? { budgetStrategy: compile.budgetStrategy } : {}),
         ...(compile?.maxContextChars !== undefined ? { maxContextChars: compile.maxContextChars } : {}),
         ...(compile?.mode !== undefined ? { mode: compile.mode } : {}),
         ...(compile?.compactionMode !== undefined ? { compactionMode: compile.compactionMode } : {}),
@@ -1589,6 +1801,7 @@ export function runRuntimeTurn(turn, options = {}) {
         message: normalizeNonEmptyString(turn.userMessage, "userMessage"),
         ...(agentId !== undefined ? { agentId } : {}),
         ...(turn.maxContextBlocks !== undefined ? { maxContextBlocks: turn.maxContextBlocks } : {}),
+        ...(turn.budgetStrategy !== undefined ? { budgetStrategy: turn.budgetStrategy } : {}),
         ...(turn.mode !== undefined ? { mode: turn.mode } : {}),
         ...(turn.runtimeHints !== undefined ? { runtimeHints: turn.runtimeHints } : {})
     };
@@ -2571,6 +2784,54 @@ function summarizeBrainState(active, observability) {
         detail
     };
 }
+function summarizeGraphObservability(active, observability) {
+    if (active === null) {
+        return {
+            available: false,
+            runtimePlasticitySource: null,
+            structuralOps: null,
+            changed: null,
+            operationsApplied: [],
+            liveBlockCount: null,
+            prunedBlockCount: null,
+            prePruneBlockCount: null,
+            strongestBlockId: null,
+            operatorSummary: null,
+            detail: "no active pack is pinned, so there is no structural graph surface to inspect"
+        };
+    }
+    const graphEvolution = observability.graphEvolutionLog;
+    if (graphEvolution === null) {
+        return {
+            available: false,
+            runtimePlasticitySource: observability.graphDynamics.runtimePlasticitySource,
+            structuralOps: null,
+            changed: null,
+            operationsApplied: [],
+            liveBlockCount: null,
+            prunedBlockCount: null,
+            prePruneBlockCount: null,
+            strongestBlockId: null,
+            operatorSummary: null,
+            detail: "active pack is present, but the graph evolution log is missing from activation observability"
+        };
+    }
+    return {
+        available: true,
+        runtimePlasticitySource: observability.graphDynamics.runtimePlasticitySource,
+        structuralOps: { ...graphEvolution.structuralOps },
+        changed: graphEvolution.structuralEvolutionSummary.changed,
+        operationsApplied: [...graphEvolution.structuralEvolutionSummary.operationsApplied],
+        liveBlockCount: graphEvolution.structuralEvolutionSummary.liveBlockCount,
+        prunedBlockCount: graphEvolution.structuralEvolutionSummary.prunedBlockCount,
+        prePruneBlockCount: graphEvolution.structuralEvolutionSummary.prePruneBlockCount,
+        strongestBlockId: graphEvolution.strongestBlockId,
+        operatorSummary: graphEvolution.structuralEvolutionSummary.operatorSummary,
+        detail: graphEvolution.structuralEvolutionSummary.changed
+            ? graphEvolution.structuralEvolutionSummary.operatorSummary
+            : "active pack graph is stable with no structural evolution beyond the current promoted artifact"
+    };
+}
 function summarizeServePath(compile) {
     if (compile === null) {
         return {
@@ -2583,6 +2844,12 @@ function summarizeServePath(compile) {
             selectionMode: null,
             refreshStatus: null,
             freshnessChecksum: null,
+            requestedBudgetStrategy: null,
+            resolvedBudgetStrategy: null,
+            resolvedMaxContextBlocks: null,
+            structuralBudgetSource: null,
+            structuralBudgetEvidence: null,
+            structuralBudgetPressures: null,
             contextAttribution: buildContextAttributionSummary({
                 fallbackToStaticContext: false,
                 hardRequirementViolated: false,
@@ -2603,10 +2870,17 @@ function summarizeServePath(compile) {
             selectionMode: null,
             refreshStatus: null,
             freshnessChecksum: null,
+            requestedBudgetStrategy: null,
+            resolvedBudgetStrategy: null,
+            resolvedMaxContextBlocks: null,
+            structuralBudgetSource: null,
+            structuralBudgetEvidence: null,
+            structuralBudgetPressures: null,
             contextAttribution: compile.contextAttribution,
             error: compile.error
         };
     }
+    const resolvedMaxContextBlocksValue = readDiagnosticNoteValue(compile.notes, "resolved_max_context_blocks=");
     return {
         state: "serving_active_pack",
         fallbackToStaticContext: compile.fallbackToStaticContext,
@@ -2617,6 +2891,13 @@ function summarizeServePath(compile) {
         selectionMode: readDiagnosticNoteValue(compile.notes, "selection_mode="),
         refreshStatus: readDiagnosticNoteValue(compile.notes, "router_refresh_status="),
         freshnessChecksum: readDiagnosticNoteValue(compile.notes, "router_freshness_checksum="),
+        requestedBudgetStrategy: readDiagnosticNoteValue(compile.notes, "requested_budget_strategy="),
+        resolvedBudgetStrategy: readDiagnosticNoteValue(compile.notes, "resolved_budget_strategy="),
+        resolvedMaxContextBlocks: resolvedMaxContextBlocksValue === null ? null : Number.parseInt(resolvedMaxContextBlocksValue, 10),
+        structuralBudgetSource: readDiagnosticNoteValue(compile.notes, "structural_budget_source="),
+        structuralBudgetEvidence: readDiagnosticNoteValue(compile.notes, "structural_budget_compile_evidence=") ??
+            readDiagnosticNoteValue(compile.notes, "structural_budget_evidence="),
+        structuralBudgetPressures: readDiagnosticNoteValue(compile.notes, "structural_budget_pressures="),
         contextAttribution: compile.contextAttribution,
         error: compile.error
     };
@@ -2649,6 +2930,112 @@ function loadOperatorEventExport(input) {
         exportedAt: null
     };
 }
+function summarizePrincipalItem(event) {
+    if (event.principal === undefined) {
+        return null;
+    }
+    return {
+        eventId: event.eventId,
+        contract: event.contract,
+        kind: event.kind,
+        sequence: event.sequence,
+        createdAt: event.createdAt,
+        teacherIdentity: event.principal.teacherIdentity,
+        teacherAuthority: event.principal.teacherAuthority,
+        priorityClass: event.principal.priorityClass,
+        scopeKind: event.principal.principalScope.kind,
+        supersedes: [...(event.principal.supersedes ?? [])]
+    };
+}
+function summarizePrincipalFeedback(event) {
+    const base = summarizePrincipalItem(event);
+    if (base === null) {
+        return null;
+    }
+    return {
+        ...base,
+        content: event.content,
+        relatedInteractionId: event.relatedInteractionId ?? null
+    };
+}
+function isPrincipalEvent(event) {
+    return event.principal?.teacherRole === "principal";
+}
+function summarizePrincipalObservability(input, active) {
+    const loaded = loadOperatorEventExport(input);
+    if (loaded === null) {
+        return {
+            available: false,
+            sourcePath: null,
+            sourceKind: "missing",
+            latestFeedback: null,
+            latestCorrection: null,
+            pendingCount: null,
+            pendingItems: [],
+            latestPromotion: {
+                known: false,
+                at: null,
+                activePackId: active?.packId ?? null,
+                activeEventRangeEnd: active?.eventRange.end ?? null,
+                includesLatestFeedback: null,
+                includesLatestCorrection: null,
+                note: "no event export path supplied"
+            },
+            servingDownstreamOfLatestCorrection: null,
+            detail: "no event export path supplied"
+        };
+    }
+    const allPrincipalEvents = sortNormalizedEvents([
+        ...loaded.normalizedEventExport.interactionEvents,
+        ...loaded.normalizedEventExport.feedbackEvents
+    ]).filter(isPrincipalEvent);
+    const principalFeedbackEvents = loaded.normalizedEventExport.feedbackEvents
+        .filter((event) => isPrincipalEvent(event))
+        .sort((left, right) => {
+        if (left.sequence !== right.sequence) {
+            return right.sequence - left.sequence;
+        }
+        return right.createdAt.localeCompare(left.createdAt);
+    });
+    const latestFeedbackEvent = principalFeedbackEvents[0] ?? null;
+    const latestCorrectionEvent = principalFeedbackEvents.find((event) => event.kind === "correction") ?? null;
+    const activeEventRangeEnd = active?.eventRange.end ?? null;
+    const pendingEvents = activeEventRangeEnd === null ? allPrincipalEvents : allPrincipalEvents.filter((event) => event.sequence > activeEventRangeEnd);
+    const includesLatestFeedback = latestFeedbackEvent === null ? null : activeEventRangeEnd !== null && latestFeedbackEvent.sequence <= activeEventRangeEnd;
+    const includesLatestCorrection = latestCorrectionEvent === null ? null : activeEventRangeEnd !== null && latestCorrectionEvent.sequence <= activeEventRangeEnd;
+    return {
+        available: true,
+        sourcePath: loaded.sourcePath,
+        sourceKind: loaded.sourceKind,
+        latestFeedback: latestFeedbackEvent === null ? null : summarizePrincipalFeedback(latestFeedbackEvent),
+        latestCorrection: latestCorrectionEvent === null ? null : summarizePrincipalFeedback(latestCorrectionEvent),
+        pendingCount: pendingEvents.length,
+        pendingItems: pendingEvents.map((event) => summarizePrincipalItem(event)).filter((item) => item !== null),
+        latestPromotion: {
+            known: active !== null && active.eventRange.count > 0,
+            at: active?.updatedAt ?? null,
+            activePackId: active?.packId ?? null,
+            activeEventRangeEnd,
+            includesLatestFeedback,
+            includesLatestCorrection,
+            note: active === null
+                ? "no active pack is serving, so principal promotion state is not observable"
+                : active.eventRange.count === 0
+                    ? "active pack is still awaiting the first export, so no principal event has been promoted into serving"
+                    : includesLatestFeedback === true
+                        ? "active serving range already covers the latest principal feedback"
+                        : latestFeedbackEvent === null
+                            ? "no principal feedback is present in the supplied export"
+                            : "latest principal feedback sits ahead of the active serving range"
+        },
+        servingDownstreamOfLatestCorrection: includesLatestCorrection,
+        detail: latestFeedbackEvent === null
+            ? "the supplied export does not contain principal feedback"
+            : pendingEvents.length === 0
+                ? "principal feedback is visible and current serving is caught up to the supplied export"
+                : `${pendingEvents.length} principal item(s) are newer than the active serving range`
+    };
+}
 function summarizeSupervision(input) {
     const loaded = loadOperatorEventExport(input);
     if (loaded === null) {
@@ -2747,7 +3134,13 @@ function summarizeTeacherLoop(input) {
         detail: "async teacher diagnostics loaded"
     };
 }
-function summarizeAlwaysOnLearning(input) {
+function summarizeAlwaysOnLearning(input, active) {
+    const unavailableLag = {
+        activeEventRangeEnd: active?.eventRange.end ?? null,
+        latestPrincipalSequence: null,
+        sequenceLag: null,
+        status: "unavailable"
+    };
     const teacherSnapshotPath = normalizeOptionalString(input.teacherSnapshotPath);
     if (teacherSnapshotPath === undefined) {
         return {
@@ -2760,6 +3153,11 @@ function summarizeAlwaysOnLearning(input) {
             pendingBackfill: null,
             pendingTotal: null,
             freshLivePriority: null,
+            principalCheckpointCount: null,
+            pendingPrincipalCount: null,
+            oldestUnlearnedPrincipalEvent: null,
+            principalCheckpoints: [],
+            principalLagToPromotion: unavailableLag,
             learnedRange: null,
             materializationCount: null,
             lastMaterializedAt: null,
@@ -2782,6 +3180,11 @@ function summarizeAlwaysOnLearning(input) {
             pendingBackfill: null,
             pendingTotal: null,
             freshLivePriority: null,
+            principalCheckpointCount: null,
+            pendingPrincipalCount: null,
+            oldestUnlearnedPrincipalEvent: null,
+            principalCheckpoints: [],
+            principalLagToPromotion: unavailableLag,
             learnedRange: null,
             materializationCount: null,
             lastMaterializedAt: null,
@@ -2793,6 +3196,17 @@ function summarizeAlwaysOnLearning(input) {
         };
     }
     const plan = describeAlwaysOnLearningRuntimeState(snapshot.learner.state, snapshot.learner.lastMaterialization);
+    const latestPrincipalSequence = plan.principalBacklog.checkpoints.reduce((latest, checkpoint) => {
+        const candidate = checkpoint.newestPendingSequence ?? checkpoint.learnedThroughSequence;
+        if (candidate === null) {
+            return latest;
+        }
+        return latest === null ? candidate : Math.max(latest, candidate);
+    }, null);
+    const activeEventRangeEnd = active?.eventRange.end ?? null;
+    const sequenceLag = latestPrincipalSequence === null || activeEventRangeEnd === null
+        ? null
+        : Math.max(latestPrincipalSequence - activeEventRangeEnd, 0);
     return {
         available: true,
         sourcePath: path.resolve(teacherSnapshotPath),
@@ -2803,6 +3217,20 @@ function summarizeAlwaysOnLearning(input) {
         pendingBackfill: plan.pending.backfill,
         pendingTotal: plan.pending.total,
         freshLivePriority: plan.pending.freshLivePriority,
+        principalCheckpointCount: plan.principalBacklog.principalCount,
+        pendingPrincipalCount: plan.principalBacklog.pendingEventCount,
+        oldestUnlearnedPrincipalEvent: plan.principalBacklog.oldestUnlearnedEvent,
+        principalCheckpoints: plan.principalBacklog.checkpoints,
+        principalLagToPromotion: {
+            activeEventRangeEnd,
+            latestPrincipalSequence,
+            sequenceLag,
+            status: sequenceLag === null
+                ? "unavailable"
+                : sequenceLag === 0
+                    ? "caught_up"
+                    : "pending_promotion"
+        },
         learnedRange: plan.learnedRange === null ? null : { ...plan.learnedRange },
         materializationCount: plan.materialization.count,
         lastMaterializedAt: plan.materialization.lastMaterializedAt,
@@ -2849,6 +3277,7 @@ function buildOperatorFindings(report) {
     }
     if (report.servePath.state === "serving_active_pack") {
         push("pass", "serve_path_verified", `serve path compiles from active pack ${report.servePath.activePackId ?? "unknown-pack"}`, `selection=${report.servePath.selectionMode ?? "unknown"}; tiers=${report.servePath.contextAttribution.selectionTiers ?? "unknown"}; router=${report.servePath.routerIdentity ?? "none"}; routeFreshness=${report.servePath.freshnessChecksum ?? "unknown"}`);
+        push("pass", "structural_budget_visible", `structural budget resolves to ${report.servePath.resolvedMaxContextBlocks ?? "unknown"} blocks`, `requested=${report.servePath.requestedBudgetStrategy ?? "unknown"}; resolved=${report.servePath.resolvedBudgetStrategy ?? "unknown"}; source=${report.servePath.structuralBudgetSource ?? "unknown"}; evidence=${report.servePath.structuralBudgetEvidence ?? "none"}; pressures=${report.servePath.structuralBudgetPressures ?? "none"}`);
     }
     else if (report.servePath.state === "fail_open_static_context") {
         push("warn", "serve_path_fail_open", "serve path would fail open to static context", report.servePath.error ?? "compile probe fell back to static context");
@@ -3102,6 +3531,7 @@ export function buildOperatorSurfaceReport(input) {
             candidateAheadBy: summarizeCandidateAheadBy(observability.promotionFreshness.candidateAheadBy)
         },
         brain: summarizeBrainState(active, observability),
+        graph: summarizeGraphObservability(active, observability),
         learnedRouting: {
             required: observability.learnedRouteFn.required,
             available: observability.learnedRouteFn.available,
@@ -3139,8 +3569,9 @@ export function buildOperatorSurfaceReport(input) {
             state: inspection.rollback.allowed ? "ready" : inspection.active === null ? "unknown" : "blocked"
         },
         supervision: summarizeSupervision(input),
-        learning: summarizeAlwaysOnLearning(input),
-        teacherLoop: summarizeTeacherLoop(input)
+        learning: summarizeAlwaysOnLearning(input, active),
+        teacherLoop: summarizeTeacherLoop(input),
+        principal: summarizePrincipalObservability(input, active)
     };
     const findings = buildOperatorFindings(reportBase);
     return {