@principles/host-runtime 0.10.4 → 0.12.0

package/dist/active-principle-prompt.d.ts

@@ -1,4 +1,4 @@
-import { type ActivatedPrinciple, type PromptSelectionPolicy } from '@principles/core/runtime-v2';
+import { type ActivatedPrinciple, type PromptBudgetResolution, type PromptSelectionPolicy } from '@principles/core/runtime-v2';
 /** PRI-904 SPEC §10: bounded diagnostic id lists (mirrors the core selector's cap of 16). */
 export declare const MAX_SHARED_DIAGNOSTIC_IDS = 16;
 export interface ActivePrinciplePromptResult {
@@ -23,6 +23,20 @@ export interface ActivePrinciplePromptResult {
     droppedActivationIds?: string[];
     /** PRI-904 (bounded, max 16): activation ids that cannot fit even in an empty payload. */
     oversizedActivationIds?: string[];
+    /**
+     * SPEC-PD-MODEL-AWARE-PROMPT-BUDGET-001: provenance of the `budget` this
+     * selection ran under (capacity source/status + the resolved context
+     * window). Present on every result; `legacy_fallback` + `unknown` means
+     * no model capacity could be confirmed and the fixed budget was used.
+     */
+    budgetCapacitySource?: PromptBudgetResolution['capacitySource'];
+    budgetCapacityStatus?: PromptBudgetResolution['capacityStatus'];
+    budgetContextWindowTokens?: number | null;
+    budgetPolicyVersion?: PromptBudgetResolution['policyVersion'];
+    /** SPEC §7 v0.2: bounded fallback reason code; present only on legacy_fallback. */
+    budgetFallbackReason?: PromptBudgetResolution['fallbackReason'];
+    /** Non-sensitive log context (provider/model ids); never emitted to events. */
+    budgetFallbackDetail?: string;
 }
 export interface PromptActivationCandidates {
     principles: ActivatedPrinciple[];
@@ -52,4 +66,12 @@ export declare function buildActivePrinciplePromptContext(input: {
      * characterization baseline).
      */
     roundKey?: number;
+    /**
+     * SPEC-PD-MODEL-AWARE-PROMPT-BUDGET-001 §6.1: the budget resolution for
+     * THIS request, resolved once by the entry point that holds the model
+     * facts. Absent → the resolver's no-facts default (legacy fixed 2000,
+     * capacityStatus unknown) — the historical behavior, used by callers with
+     * no model context (console projections, WorkBuddy without model facts).
+     */
+    promptBudget?: PromptBudgetResolution;
 }): Promise<ActivePrinciplePromptResult>;

package/dist/active-principle-prompt.js

@@ -1,4 +1,4 @@
-import { RUNTIME_V2_PRINCIPLE_BUDGET, SqliteActivationStateStore, SqliteConnection, SqlitePIArtifactStore, computeFeatureFlagsFromConfig, filterPromptActivations, renderPrinciplesToDirectives, resolvePrincipleFromArtifact, } from '@principles/core/runtime-v2';
+import { SqliteActivationStateStore, SqliteConnection, SqlitePIArtifactStore, computeFeatureFlagsFromConfig, filterPromptActivations, renderPrinciplesToDirectives, resolvePrincipleFromArtifact, resolvePromptBudget, } from '@principles/core/runtime-v2';
 import fs from 'node:fs';
 import path from 'node:path';
 import { escapeXml } from '@principles/core/prompt-builder';
@@ -81,13 +81,23 @@ export async function readPromptActivationCandidates(input) {
     return { principles, excludedPrincipleIds, warnings, aborted: false, selfReportEnabled, abstractionLayerEnabled };
 }
 export async function buildActivePrinciplePromptContext(input) {
+    // One resolution per request (SPEC §6.1): the caller's pre-resolved budget
+    // or the fixed-fallback default — never a per-line constant read.
+    const promptBudget = input.promptBudget ?? resolvePromptBudget();
+    const { budgetChars } = promptBudget;
     const { principles, excludedPrincipleIds, warnings, aborted, selfReportEnabled } = await readPromptActivationCandidates(input);
     if (aborted) {
         return {
             additionalContext: '', principleIds: [], activationIds: [], artifactIds: [], warnings,
-            budget: RUNTIME_V2_PRINCIPLE_BUDGET, truncated: false, excludedPrincipleIds,
+            budget: budgetChars, truncated: false, excludedPrincipleIds,
             excludedCount: excludedPrincipleIds.length, allValidatedPrinciplesExcluded: false,
             selectionPolicy: 'legacy_fifo_prefix_v1', eligibleCount: 0,
+            budgetCapacitySource: promptBudget.capacitySource,
+            budgetCapacityStatus: promptBudget.capacityStatus,
+            budgetContextWindowTokens: promptBudget.contextWindowTokens,
+            budgetPolicyVersion: promptBudget.policyVersion,
+            ...(promptBudget.fallbackReason !== undefined ? { budgetFallbackReason: promptBudget.fallbackReason } : {}),
+            ...(promptBudget.fallbackDetail !== undefined ? { budgetFallbackDetail: promptBudget.fallbackDetail } : {}),
         };
     }
     const included = [];
@@ -109,14 +119,14 @@ export async function buildActivePrinciplePromptContext(input) {
     const droppedActivationIds = [];
     const oversizedActivationIds = [];
     const standaloneFits = (principle) => renderPrinciplesToDirectives([principle], new Set([principle.principleId]), { escapeFn: escapeXml, selfReportInstruction: selfReportEnabled }).length
-        <= RUNTIME_V2_PRINCIPLE_BUDGET;
+        <= budgetChars;
     const scanOrder = rotationStartIndex === undefined
         ? principles
         : principles.slice(rotationStartIndex).concat(principles.slice(0, rotationStartIndex));
     for (const principle of scanOrder) {
         const candidate = [...included, principle];
         const candidateContext = renderPrinciplesToDirectives(candidate, new Set(candidate.map((entry) => entry.principleId)), { escapeFn: escapeXml, selfReportInstruction: selfReportEnabled });
-        if (candidateContext.length > RUNTIME_V2_PRINCIPLE_BUDGET) {
+        if (candidateContext.length > budgetChars) {
             if (standaloneFits(principle)) {
                 // Fits alone but not now — normal budget truncation.
                 truncated = true;
@@ -144,7 +154,7 @@ export async function buildActivePrinciplePromptContext(input) {
         activationIds: included.map((principle) => principle.activationId),
         artifactIds: included.map((principle) => principle.artifactId),
         warnings,
-        budget: RUNTIME_V2_PRINCIPLE_BUDGET,
+        budget: budgetChars,
         truncated,
         excludedPrincipleIds,
         excludedCount: excludedPrincipleIds.length,
@@ -155,5 +165,11 @@ export async function buildActivePrinciplePromptContext(input) {
         ...(rotationStartIndex !== undefined ? { rotationStartIndex } : {}),
         ...(droppedActivationIds.length > 0 ? { droppedActivationIds } : {}),
         ...(oversizedActivationIds.length > 0 ? { oversizedActivationIds } : {}),
+        budgetCapacitySource: promptBudget.capacitySource,
+        budgetCapacityStatus: promptBudget.capacityStatus,
+        budgetContextWindowTokens: promptBudget.contextWindowTokens,
+        budgetPolicyVersion: promptBudget.policyVersion,
+        ...(promptBudget.fallbackReason !== undefined ? { budgetFallbackReason: promptBudget.fallbackReason } : {}),
+        ...(promptBudget.fallbackDetail !== undefined ? { budgetFallbackDetail: promptBudget.fallbackDetail } : {}),
     };
 }

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from './prompt-injection-projection.js';
 export * from './prompt-activation-deliverability.js';
 export * from './prompt-injection-status.js';
 export * from './prompt-injection-event-evidence.js';
+export * from './prompt-injection-budget-observation.js';
 export * from './pd-config.js';
 export * from './production-rulehost-gate.js';
 export * from './rule-implementation-runtime.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { isHostEvent, isHostEventResult, } from '@principles/core/host';
-import { RUNTIME_V2_PRINCIPLE_BUDGET } from '@principles/core/runtime-v2';
+import { getPromptModelCatalog, resolvePromptBudget } from '@principles/core/runtime-v2';
 import { buildActivePrinciplePromptContext } from './active-principle-prompt.js';
 import { createProductionRuleHostGate } from './production-rulehost-gate.js';
 import { createProductionPainEvidenceHandler } from './production-pain-evidence.js';
@@ -15,6 +15,10 @@ export * from './prompt-injection-status.js';
 // SPEC PD_PROMPT_CAPACITY_V1 Phase C (AC-12): honest read-model over the
 // existing injection-event JSONL — unknown vs proven-zero never conflated.
 export * from './prompt-injection-event-evidence.js';
+// PRI-1017: runtime budget OBSERVATION read model over the SAME injection
+// events — console surfaces forecast under the budget the last real
+// injection used (SPEC §6.1), labelled with source + observation time.
+export * from './prompt-injection-budget-observation.js';
 export * from './pd-config.js';
 export * from './production-rulehost-gate.js';
 export * from './rule-implementation-runtime.js';
@@ -211,6 +215,26 @@ export function createProductionHostRuntime(options = {}) {
             const prompt = await buildActivePrinciplePromptContext({
                 workspaceDir: event.context.workspaceDir,
                 excludePrincipleIds: options.promptExcludePrincipleIds?.(event),
+                promptBudget: resolvePromptBudget({
+                    // SPEC-PD-MODEL-AWARE-PROMPT-BUDGET-001: resolve ONCE per request
+                    // from the host's own hook facts (OpenClaw effective window /
+                    // Codex+WorkBuddy model id) against the installed local Pi AI
+                    // catalog — no network, no LLM call. Missing/untrusted facts
+                    // resolve to the legacy fixed budget with an observable reason.
+                    hostCapacity: event.context.modelContext === undefined
+                        ? undefined
+                        : {
+                            contextTokenBudget: event.context.modelContext.contextTokenBudget,
+                            contextWindowSource: event.context.modelContext.contextWindowSource,
+                        },
+                    modelIdentity: event.context.modelContext === undefined
+                        ? undefined
+                        : {
+                            providerId: event.context.modelContext.modelProviderId,
+                            modelId: event.context.modelContext.modelId,
+                        },
+                    catalog: getPromptModelCatalog(),
+                }),
             });
             // PRI-750: record the injection event on the shared path with the host
             // turn id (Codex turn_id → runId) so receipt events carry a turn-level
@@ -231,11 +255,22 @@ export function createProductionHostRuntime(options = {}) {
                     injectedCount: prompt.principleIds.length,
                     skippedWarnings: prompt.warnings,
                     injectedCharCount: prompt.additionalContext.length,
-                    budget: RUNTIME_V2_PRINCIPLE_BUDGET,
+                    budget: prompt.budget,
                     ...(options.hostKind === 'openclaw' || options.hostKind === 'codex' || options.hostKind === 'workbuddy' ? { hostKind: options.hostKind } : {}),
                     eventId: randomUUID(),
                     ...(prompt.truncated !== undefined ? { v2Truncated: prompt.truncated } : {}),
                     ...(event.context.turnId !== undefined ? { runId: event.context.turnId } : {}),
+                    // SPEC-PD-MODEL-AWARE-PROMPT-BUDGET-001: budget provenance — the
+                    // recorded budget is the one THIS injection actually ran under
+                    // (prompt.budget), never a constant restated after the fact.
+                    ...(prompt.budgetPolicyVersion !== undefined ? { budgetPolicyVersion: prompt.budgetPolicyVersion } : {}),
+                    ...(prompt.budgetCapacitySource !== undefined ? { budgetCapacitySource: prompt.budgetCapacitySource } : {}),
+                    ...(prompt.budgetCapacityStatus !== undefined ? { budgetCapacityStatus: prompt.budgetCapacityStatus } : {}),
+                    ...(prompt.budgetContextWindowTokens != null ? { budgetContextWindowTokens: prompt.budgetContextWindowTokens } : {}),
+                    // SPEC §7 v0.2: the bounded fallback reason code rides the event so
+                    // operators can tell model-identity absence from catalog ambiguity
+                    // etc. without touching logs. Detail stays out of events.
+                    ...(prompt.budgetFallbackReason !== undefined ? { budgetFallbackReason: prompt.budgetFallbackReason } : {}),
                     // PRI-904: selection diagnostics (bounded, optional). On this route
                     // the policy is legacy_fifo_prefix_v1 and NO rotation provenance is
                     // emitted — a fair claim would be untrue here (see above).

package/dist/prompt-activation-deliverability.d.ts

@@ -1,4 +1,4 @@
-import { type ActivatedPrinciple } from '@principles/core/runtime-v2';
+import { type ActivatedPrinciple, type PromptBudgetTierFit } from '@principles/core/runtime-v2';
 import { PROMPT_INJECTION_UNIT, type PromptInjectionBudgetScope, type PromptInjectionRouteDecision, type PromptInjectionRouteName, type PromptInjectionTargetHost } from './prompt-injection-projection.js';
 /**
  * SPEC PD_PROMPT_CAPACITY_V1 R-B2: ONE route-aware single-artifact capacity
@@ -25,18 +25,46 @@ export type PromptArtifactDeliverability = {
     route: PromptInjectionRouteName;
     hostKind?: PromptInjectionTargetHost;
     basis?: PromptInjectionRouteDecision['basis'];
+    /**
+     * The budget this judgment is binding against: the MINIMUM supported
+     * tier — a deliverable here fits under EVERY supported budget
+     * (SPEC-PD-MODEL-AWARE-PROMPT-BUDGET-001 §6.3), so the strictest tier is
+     * the honest evidence.
+     */
     budget: number;
+    budgetMinChars: number;
+    budgetMaxChars: number;
     /** Single-item cost in UTF-16 code units under the bound route's serializer. */
     costChars: number;
     budgetScope: PromptInjectionBudgetScope;
     unit: typeof PROMPT_INJECTION_UNIT;
+} | {
+    /**
+     * SPEC-PD-MODEL-AWARE-PROMPT-BUDGET-001 §6.3: the artifact fits under
+     * SOME supported budgets but not all — whether it injects depends on the
+     * runtime model's context window. NOT a promise of injection and NOT a
+     * permanent refusal; approval flow proceeds unchanged.
+     */
+    status: 'model_dependent';
+    route: PromptInjectionRouteName;
+    hostKind?: PromptInjectionTargetHost;
+    basis?: PromptInjectionRouteDecision['basis'];
+    budgetMinChars: number;
+    budgetMaxChars: number;
+    costChars: number;
+    budgetScope: PromptInjectionBudgetScope;
+    unit: typeof PROMPT_INJECTION_UNIT;
+    nextAction: string;
 } | {
     status: 'undeliverable';
     reason: 'single_item_exceeds_budget';
     route: PromptInjectionRouteName;
     hostKind?: PromptInjectionTargetHost;
     basis?: PromptInjectionRouteDecision['basis'];
+    /** The budget this judgment is binding against: the MAXIMUM supported tier. */
     budget: number;
+    budgetMinChars: number;
+    budgetMaxChars: number;
     costChars: number;
     overByChars: number;
     budgetScope: PromptInjectionBudgetScope;
@@ -47,10 +75,10 @@ export type PromptArtifactDeliverability = {
     /** Stable machine-readable reason (route facts or artifact content unresolvable). */
     reason: string;
     nextAction: string;
-    /** Route-unconfirmed case: per-host single-item fit so the UI can show both. */
+    /** Route-unconfirmed case: per-host single-item tier fit so the UI can show both. */
     perHost?: readonly {
         hostKind: PromptInjectionTargetHost;
-        fits: boolean;
+        tierFit: PromptBudgetTierFit;
         costChars: number;
     }[];
 };
@@ -72,11 +100,16 @@ export declare function resolvePromptCandidatePrinciple(artifact: PromptDelivera
  * lines). For an entry that does NOT fit, trimToBudget returns only the
  * header line, so the would-be cost is reconstructed from the header line it
  * DID return plus the real entry line (same format authority, listEntryLine).
+ *
+ * The budget parameter defaults to the legacy fixed budget: approval-time
+ * callers hold no runtime model facts, and SPEC §6.3 requires the fixed
+ * fallback — never an invented capacity — when none can be confirmed.
  */
 export declare function computePromptSingleItemFit(input: {
     principle: ActivatedPrinciple;
     route: PromptInjectionRouteName;
     selfReportEnabled: boolean;
+    budget?: number;
 }): {
     fits: boolean;
     costChars: number;

package/dist/prompt-activation-deliverability.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { RUNTIME_V2_PRINCIPLE_BUDGET, SqliteConnection, SqlitePIArtifactStore, computeFeatureFlagsFromConfig, listEntryLine, renderPrinciplesToDirectives, resolvePrincipleFromArtifact, trimToBudget, } from '@principles/core/runtime-v2';
+import { PROMPT_BUDGET_FALLBACK_CHARS, PROMPT_BUDGET_MAX_CHARS, PROMPT_BUDGET_MIN_CHARS, SqliteConnection, SqlitePIArtifactStore, classifySingleItemBudgetTier, computeFeatureFlagsFromConfig, listEntryLine, renderPrinciplesToDirectives, resolvePrincipleFromArtifact, trimToBudget, } from '@principles/core/runtime-v2';
 import { escapeXml } from '@principles/core/prompt-builder';
 import { loadPdConfigForPlugin } from './pd-config.js';
 import { PROMPT_INJECTION_TARGET_HOSTS, PROMPT_INJECTION_UNIT, promptRouteForHost, resolvePromptInjectionRouteDecision, } from './prompt-injection-projection.js';
@@ -38,13 +38,18 @@ function selfReportEnabledFor(workspaceDir) {
  * lines). For an entry that does NOT fit, trimToBudget returns only the
  * header line, so the would-be cost is reconstructed from the header line it
  * DID return plus the real entry line (same format authority, listEntryLine).
+ *
+ * The budget parameter defaults to the legacy fixed budget: approval-time
+ * callers hold no runtime model facts, and SPEC §6.3 requires the fixed
+ * fallback — never an invented capacity — when none can be confirmed.
  */
 export function computePromptSingleItemFit(input) {
+    const budget = input.budget ?? PROMPT_BUDGET_FALLBACK_CHARS;
     if (input.route === 'shared_render') {
         const render = renderPrinciplesToDirectives([input.principle], new Set([input.principle.principleId]), { escapeFn: escapeXml, selfReportInstruction: input.selfReportEnabled });
-        return { fits: render.length <= RUNTIME_V2_PRINCIPLE_BUDGET, costChars: render.length };
+        return { fits: render.length <= budget, costChars: render.length };
     }
-    const trimmed = trimToBudget([input.principle], RUNTIME_V2_PRINCIPLE_BUDGET, escapeXml);
+    const trimmed = trimToBudget([input.principle], budget, escapeXml);
     const fits = trimmed.injectedIds.has(input.principle.principleId);
     const costChars = trimmed.lines.length > 1
         ? trimmed.lines.join('\n').length
@@ -52,6 +57,7 @@ export function computePromptSingleItemFit(input) {
     return { fits, costChars };
 }
 const UNDELIVERABLE_NEXT_ACTION = 'shorten the principle statement and resubmit, or use the activations page "modify to injectable version" entry to create a replacement artifact (the approval facts are preserved)';
+const MODEL_DEPENDENT_NEXT_ACTION = 'this principle fits the injection budget only on models with a larger context window; it may be excluded at runtime on smaller-context models — the approval itself is unaffected';
 /**
  * Precheck one artifact against the workspace's effective injection route.
  * Pure read — no state mutation, safe to call before any governance write.
@@ -78,7 +84,7 @@ export async function checkPromptArtifactDeliverability(input) {
         targetHost: input.targetHost,
     });
     if (decision.status === 'confirmed' && decision.route !== undefined) {
-        const { fits, costChars } = computePromptSingleItemFit({
+        const { costChars } = computePromptSingleItemFit({
             principle: resolved.principle,
             route: decision.route,
             selfReportEnabled,
@@ -86,44 +92,56 @@ export async function checkPromptArtifactDeliverability(input) {
         const budgetScope = decision.route === 'shared_render'
             ? 'full_directive_context'
             : 'selected_lines';
-        if (fits) {
+        const shared = {
+            route: decision.route,
+            ...(decision.hostKind !== undefined ? { hostKind: decision.hostKind } : {}),
+            ...(decision.basis !== undefined ? { basis: decision.basis } : {}),
+            budgetMinChars: PROMPT_BUDGET_MIN_CHARS,
+            budgetMaxChars: PROMPT_BUDGET_MAX_CHARS,
+            costChars,
+            budgetScope,
+            unit: PROMPT_INJECTION_UNIT,
+        };
+        // SPEC §6.3: approval time holds no runtime model identity — classify
+        // against the SUPPORTED budget range instead of pretending to know the
+        // executing model's window.
+        const tierFit = classifySingleItemBudgetTier(costChars);
+        if (tierFit === 'fits_all_tiers') {
             return {
                 status: 'deliverable',
-                route: decision.route,
-                ...(decision.hostKind !== undefined ? { hostKind: decision.hostKind } : {}),
-                ...(decision.basis !== undefined ? { basis: decision.basis } : {}),
-                budget: RUNTIME_V2_PRINCIPLE_BUDGET,
-                costChars,
-                budgetScope,
-                unit: PROMPT_INJECTION_UNIT,
+                ...shared,
+                budget: PROMPT_BUDGET_MIN_CHARS,
+            };
+        }
+        if (tierFit === 'model_dependent') {
+            return {
+                status: 'model_dependent',
+                ...shared,
+                nextAction: MODEL_DEPENDENT_NEXT_ACTION,
             };
         }
         return {
             status: 'undeliverable',
+            ...shared,
             reason: 'single_item_exceeds_budget',
-            route: decision.route,
-            ...(decision.hostKind !== undefined ? { hostKind: decision.hostKind } : {}),
-            ...(decision.basis !== undefined ? { basis: decision.basis } : {}),
-            budget: RUNTIME_V2_PRINCIPLE_BUDGET,
-            costChars,
-            overByChars: costChars - RUNTIME_V2_PRINCIPLE_BUDGET,
-            budgetScope,
-            unit: PROMPT_INJECTION_UNIT,
+            budget: PROMPT_BUDGET_MAX_CHARS,
+            overByChars: costChars - PROMPT_BUDGET_MAX_CHARS,
             nextAction: UNDELIVERABLE_NEXT_ACTION,
         };
     }
-    // Route unconfirmed: report per-host fit for every standard host instead of
-    // guessing (R-A1) — the write gate refuses, the UI can show both facts.
-    // Roster derives from the single SSoT list (review P3-1: a hand-typed
-    // two-host array dropped WorkBuddy from unconfirmed deliverability reports).
+    // Route unconfirmed: report per-host tier fit for every standard host
+    // instead of guessing (R-A1) — the write gate refuses, the UI can show
+    // both facts. Roster derives from the single SSoT list (review P3-1: a
+    // hand-typed two-host array dropped WorkBuddy from unconfirmed
+    // deliverability reports).
     const perHost = PROMPT_INJECTION_TARGET_HOSTS.map((hostKind) => {
         const route = promptRouteForHost(hostKind, decision.flagEnabled);
-        const { fits, costChars } = computePromptSingleItemFit({
+        const { costChars } = computePromptSingleItemFit({
             principle: resolved.principle,
             route,
             selfReportEnabled,
         });
-        return { hostKind, fits, costChars };
+        return { hostKind, tierFit: classifySingleItemBudgetTier(costChars), costChars };
     });
     return {
         status: 'unconfirmed',

package/dist/prompt-injection-budget-observation.d.ts

@@ -0,0 +1,176 @@
+import { PROMPT_BUDGET_POLICY_VERSION, type PromptBudgetCapacitySource, type PromptBudgetCapacityStatus, type PromptBudgetFallbackReason, type PromptBudgetResolution } from '@principles/core/runtime-v2';
+import { type PromptInjectionTargetHost } from './prompt-injection-projection.js';
+/**
+ * PRI-1017: runtime budget OBSERVATION read model over the EXISTING
+ * injection-event JSONL (`<workspaceDir>/{.pd,.state}/logs/events_<date>.jsonl`,
+ * written by the OpenClaw EventLog and the Codex/WorkBuddy shared path via
+ * appendEventLogLine).
+ *
+ * Why this exists: SPEC-PD-MODEL-AWARE-PROMPT-BUDGET-001 §6.1 forbids the
+ * actual injection from running a dynamic budget while the Console forecasts
+ * under a different fixed 2000-char budget. The console holds no live host
+ * facts, but the RUNTIME persists the resolution it actually used —
+ * `runtime_v2_prompt_activations_injected` carries budgetChars, capacity
+ * provenance and hostKind. This module reads those facts back so console
+ * surfaces forecast under the same budget the last real injection used.
+ *
+ * Honesty rules this model enforces (SPEC §6.1/§7):
+ * - An observation is a FACT ABOUT THE PAST, never a live claim: callers must
+ *   surface `observedAt`; the console labels it "most recent runtime
+ *   observation", not a current confirmation.
+ * - No logs / no budget facts ⇒ absent, never a fabricated window; the caller
+ *   keeps the honest fixed-fallback policy.
+ * - A latest observation older than RUNTIME_BUDGET_OBSERVATION_MAX_AGE_MS is
+ *   `stale` — the caller must NOT present it as the current budget.
+ * - Observations bind to ONE host: OpenClaw's window is never used for a
+ *   Codex or WorkBuddy forecast.
+ * - Untrusted input discipline: every line is parsed as `unknown` and
+ *   narrowed with typeof guards + closed-set checks; structurally invalid
+ *   lines are counted in `parseFailures` and skipped loudly, never guessed.
+ * - Events predating the model-aware policy carry no provenance fields; they
+ *   are counted as `legacyEventsSkipped` and produce NO observation — a
+ *   missing provenance field is "policy unknown", never a capacity claim.
+ * - Bounded I/O: only the newest bytes of the most recent daily files are read
+ *   (tail window), the file cap applying PER candidate log directory, so a
+ *   runaway or crafted log cannot make a Console request read an unbounded
+ *   amount of data. Only bounded budget metadata is retained and returned;
+ *   other event payloads are not cached.
+ */
+/**
+ * Candidate directories for the runtime-v2 event log, in priority order.
+ * Shared with the RuleCode telemetry collector (ERR-031: both readers derive
+ * from one list — the v1 EventLog writer emits `.state/logs`, no production
+ * code ever created `.pd/logs`).
+ */
+export declare const RUNTIME_V2_EVENT_LOG_CANDIDATE_DIRS: readonly string[];
+/**
+ * Bounded I/O: only the most recent daily files are scanned — PER candidate
+ * log directory (`RUNTIME_V2_EVENT_LOG_CANDIDATE_DIRS`), not globally. The
+ * cap is deliberately per directory: both directories describe the same
+ * workspace's log convention and either can hold the newest event for a given
+ * host (the reader takes latest-wins ACROSS them), so a global cap would let
+ * one directory's files starve the other and drop a live host observation.
+ * Worst case per read is therefore `RUNTIME_BUDGET_OBSERVATION_MAX_FILES ×
+ * RUNTIME_V2_EVENT_LOG_CANDIDATE_DIRS.length` files (14 today) and the same
+ * count × `RUNTIME_BUDGET_OBSERVATION_MAX_FILE_BYTES` bytes (56 MiB today).
+ */
+export declare const RUNTIME_BUDGET_OBSERVATION_MAX_FILES = 7;
+/**
+ * Bounded I/O: per file, only the newest bytes are read. The writer appends,
+ * so the latest observation per host lives at the TAIL; a file larger than
+ * this window is tail-read and its older prefix skipped (counted in
+ * `truncatedFiles`) instead of materialising an unbounded log in the console
+ * process. 4 MiB is ~3.4x the largest real day observed on 2026-10-21
+ * (WorkBuddy 1.17 MiB, Codex 0.87 MiB, OpenClaw 0.98 MiB across 7 files).
+ */
+export declare const RUNTIME_BUDGET_OBSERVATION_MAX_FILE_BYTES: number;
+/**
+ * Maximum age of an observation that may be presented as a CURRENT runtime
+ * fact. The runtime refreshes the observation on every prompt build, so an
+ * active workspace holds minute-old facts; beyond a day the model may have
+ * been switched and the window is no longer evidence about the present.
+ */
+export declare const RUNTIME_BUDGET_OBSERVATION_MAX_AGE_MS: number;
+/**
+ * Clock-skew allowance for event timestamps. A writer clock ahead of ours is
+ * normal; an observation further in the future is not a fact about the
+ * present and must never be selected as the current budget.
+ */
+export declare const RUNTIME_BUDGET_OBSERVATION_MAX_FUTURE_SKEW_MS: number;
+/** Console-side bounded reason: a runtime observation exists but is too old. */
+export declare const RUNTIME_BUDGET_OBSERVATION_STALE_REASON: 'runtime_budget_observation_stale';
+export interface RuntimePromptBudgetObservation {
+    /** The workspace the observed event was bound to (event `data.workspaceDir`). */
+    workspaceDir: string;
+    /** Host that produced the observation; observations never cross hosts. */
+    hostKind: PromptInjectionTargetHost;
+    /** Budget the real injection ran under (UTF-16 code units). */
+    budgetChars: number;
+    capacitySource: PromptBudgetCapacitySource;
+    capacityStatus: PromptBudgetCapacityStatus;
+    /** The context window the budget derived from; null when unknown. */
+    contextWindowTokens: number | null;
+    /** Bounded fallback reason carried by the event; null when confirmed. */
+    fallbackReason: PromptBudgetFallbackReason | null;
+    /** Policy version the observed budget was computed under (closed literal). */
+    policyVersion: typeof PROMPT_BUDGET_POLICY_VERSION | null;
+    /** ISO timestamp of the observed event (`ts` envelope field). */
+    observedAt: string;
+}
+export interface RuntimeBudgetObservationReport {
+    /** Latest observation per host (most recent by event `ts`). */
+    observations: RuntimePromptBudgetObservation[];
+    filesRead: string[];
+    lines: number;
+    parseFailures: number;
+    /** Injection events without model-aware budget provenance (pre-policy events). */
+    legacyEventsSkipped: number;
+    /** Injection events whose budget policy version differs from the current one. */
+    foreignPolicyEventsSkipped: number;
+    /**
+     * Files larger than the bounded read window whose older prefix was skipped.
+     * Non-zero means `lines`/skip counters describe the read window only.
+     */
+    truncatedFiles: number;
+    note: string;
+}
+export type RuntimeBudgetObservationSelection = {
+    kind: 'usable';
+    observation: RuntimePromptBudgetObservation;
+} | {
+    kind: 'stale';
+    observation: RuntimePromptBudgetObservation;
+} | {
+    kind: 'absent';
+};
+/**
+ * Read the most recent budget observation per host from the workspace's
+ * runtime-v2 event logs. Never throws: an unreadable log directory degrades
+ * to an empty report with an explicit note (absence is UNKNOWN, not zero).
+ */
+export declare function readRuntimePromptBudgetObservations(input: {
+    workspaceDir: string;
+    /** Reference clock for the future-timestamp guard (tests pass a fixed one). */
+    now?: Date;
+}): RuntimeBudgetObservationReport;
+/**
+ * Select the observation that may back a console forecast for `targetHost`.
+ * `absent` when the host has no observation at all; `stale` when the latest
+ * one is older than the freshness bound (the caller must fall back honestly).
+ */
+export declare function selectRuntimeBudgetObservation(input: {
+    observations: readonly RuntimePromptBudgetObservation[];
+    targetHost?: PromptInjectionTargetHost;
+    now?: Date;
+}): RuntimeBudgetObservationSelection;
+/**
+ * Console-facing selection: one call gives the confirmed-host budget basis,
+ * the honest stale marker, and the per-host bases for unconfirmed routes.
+ * Reads the workspace's event logs; never throws.
+ */
+export interface ConsoleRuntimeBudgetFacts {
+    /** Usable observation for the requested host (only when targetHost is given). */
+    selected?: RuntimePromptBudgetObservation;
+    /** Latest observation for the requested host that is too old to be current. */
+    stale?: RuntimePromptBudgetObservation;
+    /**
+     * Usable observations per host — used for unconfirmed per-host forecasts
+     * AND for a confirmed route whose host was resolved from workspace facts
+     * (no request-level targetHost). Each host only ever gets its own fact.
+     */
+    perHost: Map<PromptInjectionTargetHost, RuntimePromptBudgetObservation>;
+    /** Latest per-host observation that is too old to be presented as current. */
+    stalePerHost: Map<PromptInjectionTargetHost, RuntimePromptBudgetObservation>;
+}
+export declare function selectConsoleRuntimeBudgetFacts(input: {
+    workspaceDir: string;
+    targetHost?: PromptInjectionTargetHost;
+    now?: Date;
+}): ConsoleRuntimeBudgetFacts;
+/**
+ * Rebuild the budget resolution an observation stands for, so console
+ * projections run under the SAME resolution shape the real injection used.
+ * `fallbackDetail` is deliberately dropped: it is log-only context and never
+ * rides events or console payloads.
+ */
+export declare function runtimeBudgetObservationToResolution(observation: RuntimePromptBudgetObservation): PromptBudgetResolution;