@llblab/pi-actors 0.43.1 → 0.45.0

package/dist/lib/observability.js

@@ -7,29 +7,33 @@ import { closeSync, existsSync, fstatSync, openSync, readdirSync, readFileSync,
 import { basename, dirname, isAbsolute, join, relative, } from "node:path";
 import * as AsyncRuns from "./async-runs.js";
 import * as Paths from "./paths.js";
+import * as RunsTrace from "./runs-trace.js";
 import { readJsonlFileResilient } from "./state-readers.js";
 export function createRunUiObservationState() {
     return {
         attentionEventIds: new Map(),
-        eventLines: new Map(),
+        legacyEventLines: new Map(),
         frame: 0,
         observed: new Map(),
     };
 }
+export function primeRunAttentionState(state, ownerId, stateRoot) {
+    detectRunAttentionEvents(state.legacyEventLines, summarizeRuns(stateRoot, ownerId), state.attentionEventIds, true);
+}
 export function readRunUiSnapshot(state, ownerId, options = {}) {
     const summary = summarizeRuns(options.stateRoot, ownerId);
     const status = renderRunStatus(summary, state.frame++);
     return {
         attentionEvents: options.includeAttention === false
             ? []
-            : detectRunAttentionEvents(state.eventLines, summary, state.attentionEventIds),
+            : detectRunAttentionEvents(state.legacyEventLines, summary, state.attentionEventIds),
         status,
         summary,
         transitions: detectRunTransitions(state.observed, summary),
     };
 }
 export function pruneRunUiObservationState(state, snapshot) {
-    pruneRunObservationState(state.observed, state.eventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.attentionEventIds);
+    pruneRunObservationState(state.observed, state.legacyEventLines, snapshot.summary, snapshot.transitions.map((transition) => transition.stateDir ?? transition.run), state.attentionEventIds);
 }
 export function deliverRunTransitionNotifications(transitions, sink, inFlight = new Set()) {
     for (const transition of transitions) {
@@ -68,9 +72,11 @@ export function deliverRunTransitionNotifications(transitions, sink, inFlight =
 }
 export function reconcileRunTerminalNotifications(input) {
     const snapshot = readRunUiSnapshot(input.state, input.ownerId, {
-        includeAttention: false,
+        includeAttention: input.includeAttention,
         stateRoot: input.stateRoot,
     });
+    if (input.includeAttention)
+        deliverRunAttentionNotifications(snapshot.attentionEvents, input.sink);
     deliverRunTransitionNotifications(snapshot.transitions, input.sink, input.inFlight);
     pruneRunUiObservationState(input.state, snapshot);
     return snapshot;
@@ -769,12 +775,13 @@ function parseAttentionRecord(raw, run, index) {
 }
 function readTraceAttentionRecords(run) {
     if (!run.stateDir)
-        return [];
-    const tracePath = join(run.stateDir, "trace.jsonl");
-    if (existsSync(tracePath)) {
-        return readJsonlFileResilient(tracePath).records;
-    }
-    return readJsonlFileResilient(join(run.stateDir, "outbox.jsonl")).records;
+        return { canonical: true, records: [] };
+    if (existsSync(join(run.stateDir, "trace.jsonl")))
+        return {
+            canonical: true,
+            records: RunsTrace.readRunTraceJournal(run.stateDir).events.map(({ event }) => event),
+        };
+    return { canonical: false, records: readJsonlFileResilient(join(run.stateDir, "outbox.jsonl")).records };
 }
 export function pruneRunObservationState(previousStatuses, previousLineCounts, summary, terminalRuns = [], seenEventIds = new Map()) {
     const activeRuns = new Set(summary.runs.map((run) => runObservationKey(run)));
@@ -785,43 +792,43 @@ export function pruneRunObservationState(previousStatuses, previousLineCounts, s
     const activeLineKeys = new Set(summary.runs.map((run) => run.stateDir ?? run.run));
     for (const run of terminalRunSet)
         previousStatuses.delete(run);
-    for (const run of previousStatuses.keys()) {
+    for (const run of previousStatuses.keys())
         if (!activeRuns.has(run))
             previousStatuses.delete(run);
-    }
-    for (const key of previousLineCounts.keys()) {
-        if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
+    for (const key of previousLineCounts.keys())
+        if (terminalLineKeys.has(key) || !activeLineKeys.has(key))
             previousLineCounts.delete(key);
-        }
-    }
-    for (const key of seenEventIds.keys()) {
-        if (terminalLineKeys.has(key) || !activeLineKeys.has(key)) {
+    for (const key of seenEventIds.keys())
+        if (terminalLineKeys.has(key) || !activeLineKeys.has(key))
             seenEventIds.delete(key);
-        }
-    }
 }
-export function detectRunAttentionEvents(previousLineCounts, summary, seenEventIds = new Map()) {
+export function detectRunAttentionEvents(legacyLineCounts, summary, seenEventIds = new Map(), prime = false) {
     const events = [];
     for (const run of summary.runs) {
         const key = run.stateDir ?? run.run;
-        const records = readTraceAttentionRecords(run);
-        const previousCount = previousLineCounts.get(key) ?? 0;
-        if (run.notificationPolicy === "silent") {
-            previousLineCounts.set(key, records.length);
-            seenEventIds.set(key, seenEventIds.get(key) ?? new Set());
-            continue;
-        }
-        const start = Math.min(previousCount, records.length);
+        const read = readTraceAttentionRecords(run);
+        const retained = new Set();
         const seen = seenEventIds.get(key) ?? new Set();
-        for (let index = start; index < records.length; index += 1) {
-            const event = parseAttentionRecord(records[index], run, index);
-            if (!event || seen.has(event.id))
+        const start = read.canonical ? 0
+            : Math.min(legacyLineCounts.get(key) ?? 0, read.records.length);
+        for (const [index, record] of read.records.entries()) {
+            const event = parseAttentionRecord(record, run, index);
+            if (!event || !shouldNotifyRunAttentionEvent(event) ||
+                event.kind === "runtime.trace_compacted")
                 continue;
-            events.push(event);
-            seen.add(event.id);
+            retained.add(event.id);
+            if (prime || run.notificationPolicy === "silent")
+                seen.add(event.id);
+            else if (index >= start && !seen.has(event.id)) {
+                events.push(event);
+                seen.add(event.id);
+            }
         }
-        previousLineCounts.set(key, records.length);
-        seenEventIds.set(key, seen);
+        seenEventIds.set(key, new Set([...retained].filter((id) => seen.has(id))));
+        if (read.canonical)
+            legacyLineCounts.delete(key);
+        else
+            legacyLineCounts.set(key, read.records.length);
     }
     return events;
 }

package/dist/lib/recipes-discovery.js

@@ -53,17 +53,33 @@ function getRecipeCommandTemplateConfig(config) {
         ? config.template
         : config);
 }
+function getRecipeDiagnosticTemplateConfig(config) {
+    const templateConfig = getRecipeCommandTemplateConfig(config);
+    return typeof templateConfig === "object" && !Array.isArray(templateConfig)
+        ? {
+            ...templateConfig,
+            defaults: {
+                ...(templateConfig.defaults ?? {}),
+                ...(config.defaults ?? {}),
+                ...(config.values ?? {}),
+            },
+        }
+        : {
+            defaults: { ...(config.defaults ?? {}), ...(config.values ?? {}) },
+            template: templateConfig,
+        };
+}
 function getRecipeConfigDiagnostics(file, config) {
     if (!config) {
         const reason = RecipesReferences.diagnoseRawRecipeConfigFailure(file);
         return [`Invalid recipe: ${file}${reason ? `: ${reason}` : ""}`];
     }
-    return CommandTemplates.getCommandTemplateWarnings(getRecipeCommandTemplateConfig(config)).map((warning) => `Recipe ${file}: ${warning}`);
+    return CommandTemplates.getCommandTemplateWarnings(getRecipeDiagnosticTemplateConfig(config)).map((warning) => `Recipe ${file}: ${warning}`);
 }
 function getRecipeRiskLabels(config) {
     if (!config)
         return [];
-    const labels = new Set(CommandTemplates.getCommandTemplateRiskLabels(getRecipeCommandTemplateConfig(config)));
+    const labels = new Set(CommandTemplates.getCommandTemplateRiskLabels(getRecipeDiagnosticTemplateConfig(config)));
     if (config.async === true)
         labels.add("risk.long_running");
     return [
@@ -652,8 +668,9 @@ export function toRegisteredTool(entry) {
         const parsed = Schema.parseToolArgToken(String(arg));
         return [parsed.arg, parsed.type];
     }));
-    assertToolSafeRepeatConfig(argTemplateConfig, explicitArgTypes, cfg.defaults ?? {});
+    assertToolSafeRepeatConfig(argTemplateConfig, explicitArgTypes, { ...(cfg.defaults ?? {}), ...(cfg.values ?? {}) });
     const argTypes = Schema.getTemplateArgTypes(argTemplateConfig);
+    Schema.assertCompatibleToolArgTypes(explicitArgTypes, argTypes);
     return {
         name: entry.id,
         description,

package/dist/lib/recipes-references.d.ts

@@ -40,6 +40,8 @@ export interface TemplateRecipeDefinition {
 }
 export interface TemplateRecipeConfig extends TemplateRecipeDefinition {
     async?: boolean;
+    recipe_dir?: string;
+    skill_dir?: string;
 }
 export interface TemplateRecipeContextRecord {
     alias?: string;
@@ -47,12 +49,20 @@ export interface TemplateRecipeContextRecord {
     file: string;
     import_path: string[];
     name: string;
+    qualified_name?: string;
     recipe: Record<string, unknown>;
     role: "entry" | "import";
 }
 export interface ReadResolvedRecipeConfigOptions {
     includeActorRecipeContext?: boolean;
 }
+export interface ActiveSkillRecipeSource {
+    name: string;
+    filePath?: string;
+    baseDir?: string;
+}
+export declare function setActiveSkillRecipeSources(skills: ActiveSkillRecipeSource[]): void;
+export declare function getActiveSkillRecipeNamespaces(): Record<string, string[]>;
 export declare function resolveRecipePath(value: string, recipeRoot?: string): string;
 export declare function resolveRecipeReferencePath(value: unknown, currentRecipeRoot?: string): string | undefined;
 export declare function getRecipePath(value: unknown, recipeRoot?: string): string | undefined;

package/dist/lib/recipes-references.js

@@ -5,15 +5,106 @@
  */
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname, extname, resolve } from "node:path";
+import { basename, dirname, extname, isAbsolute, relative, resolve } from "node:path";
 import * as CommandTemplates from "./command-templates.js";
 import * as Paths from "./paths.js";
 import * as RecipeControl from "./recipe-control.js";
+import * as Schema from "./schema.js";
 const MAX_RECIPE_FILE_BYTES = 1024 * 1024;
 const MAX_RECIPE_IMPORT_DEPTH = 32;
+const RUNTIME_RECIPE_VALUE_NAMES = new Set(["recipe_dir", "skill_dir"]);
+const activeSkillRecipeRoots = new Map();
+export function setActiveSkillRecipeSources(skills) {
+    activeSkillRecipeRoots.clear();
+    for (const skill of skills) {
+        const name = skill.name.trim();
+        const skillDir = skill.baseDir
+            ? resolve(skill.baseDir)
+            : skill.filePath
+                ? dirname(resolve(skill.filePath))
+                : undefined;
+        if (!name || !skillDir)
+            continue;
+        const roots = activeSkillRecipeRoots.get(name) ?? new Set();
+        roots.add(resolve(skillDir, "recipes"));
+        activeSkillRecipeRoots.set(name, roots);
+    }
+}
+export function getActiveSkillRecipeNamespaces() {
+    return Object.fromEntries([...activeSkillRecipeRoots.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, roots]) => [name, [...roots].sort()]));
+}
+function qualifiedRecipeNameForFile(file) {
+    const path = resolve(file);
+    const stdRelation = relative(Paths.getPackagedRecipeRoot(), path);
+    if (stdRelation &&
+        !stdRelation.startsWith("..") &&
+        !isAbsolute(stdRelation)) {
+        return `std:${stdRelation.replace(/\.(?:json|md)$/u, "")}`;
+    }
+    for (const [skillName, roots] of activeSkillRecipeRoots) {
+        if (roots.size !== 1)
+            continue;
+        const root = [...roots][0];
+        const relation = relative(root, path);
+        if (relation && !relation.startsWith("..") && !isAbsolute(relation))
+            return `skill:${skillName}/${relation.replaceAll("\\", "/").replace(/\.(?:json|md)$/u, "")}`;
+    }
+    return undefined;
+}
+function qualifiedRecipeCandidates(value) {
+    if (value.startsWith("std:")) {
+        return recipeNameFiles(value.slice(4)).map((file) => resolve(Paths.getPackagedRecipeRoot(), file));
+    }
+    if (!value.startsWith("skill:"))
+        return undefined;
+    const qualified = value.slice(6);
+    const separator = qualified.indexOf("/");
+    if (separator <= 0 || separator === qualified.length - 1)
+        throw new Error(`Invalid Skill Recipe reference: ${value}`);
+    const skillName = qualified.slice(0, separator);
+    const recipeName = qualified.slice(separator + 1);
+    const roots = [...(activeSkillRecipeRoots.get(skillName) ?? [])];
+    if (roots.length === 0)
+        throw new Error(`Active Skill Recipe namespace not found: ${skillName}`);
+    if (roots.length > 1)
+        throw new Error(`Ambiguous active Skill Recipe namespace ${skillName}: ${roots.join(", ")}`);
+    const root = roots[0];
+    return recipeNameFiles(recipeName).map((file) => {
+        const candidate = resolve(root, file);
+        const relation = relative(root, candidate);
+        if (!relation || relation.startsWith("..") || isAbsolute(relation))
+            throw new Error(`Skill Recipe reference escapes its recipes root: ${value}`);
+        return candidate;
+    });
+}
 function hasWhitespace(value) {
     return /\s/.test(value);
 }
+function findOwningSkillDir(recipeFile) {
+    let current = dirname(recipeFile);
+    while (true) {
+        if (existsSync(resolve(current, "SKILL.md")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+function assertRuntimeRecipeValuesNotDeclared(raw) {
+    const args = Array.isArray(raw.args)
+        ? Schema.getExplicitToolArgNames(raw.args.map(String))
+        : [];
+    for (const name of RUNTIME_RECIPE_VALUE_NAMES) {
+        if (args.includes(name) ||
+            (isRecord(raw.defaults) && Object.hasOwn(raw.defaults, name)) ||
+            (isRecord(raw.values) && Object.hasOwn(raw.values, name))) {
+            throw new Error(`Recipe runtime value is reserved: ${name}`);
+        }
+    }
+}
 export function resolveRecipePath(value, recipeRoot = Paths.getRecipeRoot()) {
     const trimmed = value.trim();
     const repoRoot = resolve(recipeRoot, "..");
@@ -42,6 +133,9 @@ function recipeNameFiles(value) {
     return [`${trimmed}.json`, `${trimmed}.md`];
 }
 function recipeCandidatePaths(value, currentRecipeRoot) {
+    const qualified = qualifiedRecipeCandidates(value.trim());
+    if (qualified)
+        return qualified;
     if (!isBareRecipeName(value))
         return [resolveRecipePath(value, currentRecipeRoot)];
     const roots = [
@@ -495,11 +589,46 @@ function mergeDefaults(...items) {
     const merged = Object.assign({}, ...items.filter(Boolean));
     return Object.keys(merged).length > 0 ? merged : undefined;
 }
+function assertRecipeDefaultsDeclared(args, defaults, label) {
+    const spec = Schema.parseToolArgDeclarationList(args ?? []);
+    if (spec.error)
+        throw new Error(spec.error);
+    if (spec.args.length === 0)
+        return;
+    const declared = new Set(spec.args);
+    for (const key of Object.keys(defaults ?? {})) {
+        if (!declared.has(key))
+            throw new Error(`Unknown ${label} argument: ${key}`);
+    }
+}
+function assertRecipeArgumentContract(config, label = "Recipe default") {
+    assertRecipeDefaultsDeclared(config.args, config.defaults, label);
+    const spec = Schema.parseToolArgDeclarationList(config.args ?? []);
+    if (spec.error)
+        throw new Error(spec.error);
+    Schema.assertCompatibleToolArgTypes(spec.argTypes, Schema.getTemplateArgTypes({ template: config.template }));
+    const staticValues = Object.fromEntries(Object.entries({ ...config.defaults, ...config.values }).filter(([, value]) => typeof value !== "string" || !/\{[^{}]+\}/.test(value)));
+    Schema.normalizeRuntimeValues(staticValues, spec.argTypes);
+}
+function resolveRecipeValueLayers(args, ...layers) {
+    const spec = Schema.parseToolArgDeclarationList(args ?? []);
+    if (spec.error)
+        throw new Error(spec.error);
+    const merged = mergeDefaults(spec.defaults, ...layers);
+    if (!merged)
+        return undefined;
+    const staticValues = Object.fromEntries(Object.entries(merged).filter(([, value]) => typeof value !== "string" || !/\{[^{}]+\}/.test(value)));
+    return {
+        ...merged,
+        ...Schema.normalizeRuntimeValues(staticValues, spec.argTypes),
+    };
+}
 function applyDefaultsToTemplate(template, defaults, overrides) {
     const cleanOverrides = { ...overrides };
     delete cleanOverrides.name;
     delete cleanOverrides.template;
     delete cleanOverrides.values;
+    delete cleanOverrides.defaults;
     if (typeof template === "object" && !Array.isArray(template)) {
         return {
             ...template,
@@ -537,7 +666,15 @@ function loadDelegatedRecipe(value, currentRecipeFile, stack, options) {
     return config;
 }
 function applyDelegatedRecipeToNode(delegated, overrides = {}) {
-    return applyDefaultsToTemplate(delegated.template, delegated.values, overrides);
+    const nodeDefaults = isRecord(overrides.defaults)
+        ? overrides.defaults
+        : undefined;
+    const nodeValues = isRecord(overrides.values) ? overrides.values : undefined;
+    const values = resolveRecipeValueLayers(delegated.args, delegated.defaults, delegated.values, nodeDefaults, nodeValues, {
+        ...(delegated.recipe_dir ? { recipe_dir: delegated.recipe_dir } : {}),
+        ...(delegated.skill_dir ? { skill_dir: delegated.skill_dir } : {}),
+    });
+    return applyDefaultsToTemplate(delegated.template, values, overrides);
 }
 function expandRecipeDelegations(value, currentRecipeFile, stack, options = {}) {
     if (typeof value === "string") {
@@ -593,7 +730,7 @@ function expandImportNodes(value, imports, options = {}) {
             ? record.defaults
             : undefined;
         const nodeValues = isRecord(record.values) ? record.values : undefined;
-        const defaults = mergeDefaults(imported.defaults, imported.values, nodeDefaults, nodeValues);
+        const defaults = resolveRecipeValueLayers(imported.config.args, imported.defaults, imported.values, nodeDefaults, nodeValues);
         const expanded = applyDefaultsToTemplate(imported.config.template, defaults, record);
         return options.includeActorRecipeContext
             ? withActorRecipeContext(expanded, {
@@ -631,6 +768,8 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
     if (!raw || !Object.hasOwn(raw, "template"))
         return undefined;
     RecipeControl.assertRecipeHasNoMailbox(raw);
+    assertRuntimeRecipeValuesNotDeclared(raw);
+    assertRecipeArgumentContract(raw);
     const imports = {};
     for (const [alias, binding] of Object.entries(getRecipeImports(raw))) {
         const importPath = resolveRecipeImportPath(getImportFrom(binding), dirname(path));
@@ -639,13 +778,18 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
             throw new Error(`Recipe import not found: ${alias}`);
         const bindingDefaults = typeof binding === "string" ? undefined : binding.defaults;
         const bindingValues = typeof binding === "string" ? undefined : binding.values;
+        assertRecipeDefaultsDeclared(config.args, bindingDefaults, `Recipe import ${alias} default`);
         imports[alias] = {
             alias,
             file: importPath,
             name: config.name ?? alias,
             config,
             defaults: { ...(config.defaults ?? {}), ...(bindingDefaults ?? {}) },
-            values: { ...(bindingValues ?? {}) },
+            values: {
+                ...(bindingValues ?? {}),
+                ...(config.recipe_dir ? { recipe_dir: config.recipe_dir } : {}),
+                ...(config.skill_dir ? { skill_dir: config.skill_dir } : {}),
+            },
         };
     }
     const substituted = substituteImportRefs(raw, imports);
@@ -661,6 +805,17 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
             : {})
         : expandRecipeDelegations(expandedImportsTemplate, path, stack, options);
     const recipeName = getRecipeIdFromPath(path);
+    const recipeDir = dirname(path);
+    const skillDir = findOwningSkillDir(path);
+    if (!skillDir &&
+        JSON.stringify({
+            artifacts: substituted.artifacts,
+            defaults: substituted.defaults,
+            template: substituted.template,
+            values: substituted.values,
+        }).includes("{skill_dir}")) {
+        throw new Error(`Recipe uses {skill_dir} outside an owning Skill directory: ${path}`);
+    }
     const templateWithContext = options.includeActorRecipeContext
         ? withActorRecipeContext(expandedTemplate, {
             file: path,
@@ -678,6 +833,8 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         : delegated?.control);
     return {
         name: recipeName,
+        recipe_dir: recipeDir,
+        ...(skillDir ? { skill_dir: skillDir } : {}),
         ...(typeof substituted.description === "string" &&
             substituted.description.trim()
             ? { description: substituted.description.trim() }
@@ -765,7 +922,11 @@ export function readResolvedRecipeConfig(file, stack = [], options = {}) {
         ...(typeof substituted.repeat === "number"
             ? { repeat: substituted.repeat }
             : {}),
-        ...(isRecord(substituted.values) ? { values: substituted.values } : {}),
+        values: {
+            ...(isRecord(substituted.values) ? substituted.values : {}),
+            recipe_dir: recipeDir,
+            ...(skillDir ? { skill_dir: skillDir } : {}),
+        },
         ...(isRecord(substituted.usage) ? { usage: substituted.usage } : {}),
     };
 }
@@ -780,12 +941,14 @@ function collectRecipeContextRecords(file, stack, importPath, alias) {
     const raw = readRawRecipeConfig(path);
     if (!raw || !Object.hasOwn(raw, "template"))
         return [];
+    const qualifiedName = qualifiedRecipeNameForFile(path);
     const record = {
         ...(alias ? { alias } : {}),
         depth: stack.length,
         file: path,
         import_path: importPath,
         name: getRecipeIdFromPath(path),
+        ...(qualifiedName ? { qualified_name: qualifiedName } : {}),
         recipe: raw,
         role: stack.length === 0 ? "entry" : "import",
     };

package/dist/lib/run-evidence-policy.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pure bounded Run-evidence policy.
+ * Zones: Trace retention, compaction accounting, Control capacity and admission
+ * Owns deterministic limits policy; journal I/O, locks, lifecycle authorization, and projection stay in adapters.
+ * Trace keeps the newest physical suffix because semantic priority would silently
+ * redefine causal history. Admitted Controls never expire: only a real terminal
+ * transition or generation replacement proves that durable work is finished.
+ */
+export declare const TRACE_COMPACTION_KIND = "runtime.trace_compacted";
+export declare const TRACE_COMPACTION_VERSION = 1;
+export type TraceJournalUsage = {
+    bytes: number;
+    events: number;
+};
+export type TraceRetentionCandidate<T> = {
+    encodedBytes: number;
+    value: T;
+};
+export type TraceRetentionSelection<T> = {
+    droppedEvents: number;
+    retained: TraceRetentionCandidate<T>[];
+    retainedBytes: number;
+    retainedEvents: number;
+};
+export interface TraceCompactionData {
+    version: typeof TRACE_COMPACTION_VERSION;
+    compactions_total: number;
+    dropped_valid_events_total: number;
+    dropped_malformed_lines_total: number;
+    dropped_bytes_total: number;
+    dropped_event_count_exact: boolean;
+    retained_events: number;
+    retained_bytes: number;
+    history_complete: false;
+}
+export interface TraceCompactionDelta {
+    dropped_valid_events: number;
+    dropped_malformed_lines: number;
+    dropped_bytes: number;
+    dropped_event_count_exact: boolean;
+    retained_events: number;
+    retained_bytes: number;
+}
+export type RunControlStatus = "queued" | "delivered" | "claimed" | "handled" | "failed";
+export type RunControlCapacity = {
+    available: number;
+    backpressured: boolean;
+    limit: number;
+    oldest_pending_at?: string;
+    pending: number;
+};
+export type RunControlAdmissionIntegrity = "valid" | "unreadable" | "malformed" | "noncanonical" | "invalid_record" | "invalid_status_timestamp" | "generation_mismatch" | "journal_bytes";
+export interface RunControlAdmissionErrorDetails {
+    reason: "control_backpressure" | "control_journal_integrity";
+    pending: number;
+    limit: number;
+    journal_bytes: number;
+    journal_limit: number;
+    oldest_pending_at?: string;
+    run_instance_id: string;
+    next_actions: string[];
+    integrity_reason?: string;
+}
+export type RunControlAdmissionDecision = {
+    admitted: true;
+    capacity: RunControlCapacity;
+} | {
+    admitted: false;
+    capacity: RunControlCapacity;
+    error: RunControlAdmissionErrorDetails;
+};
+export type RunControlAdmissionInput = {
+    integrity: RunControlAdmissionIntegrity;
+    journalBytes: number;
+    newRecordBytes: number;
+    records: readonly unknown[];
+    retainedJournalBytes: number;
+    runInstanceId: string;
+    capacity?: RunControlCapacity;
+};
+export declare function traceAppendFits(usage: TraceJournalUsage, encodedEventBytes: number): boolean;
+export declare function selectNewestTraceSuffix<T>(candidates: readonly TraceRetentionCandidate<T>[], reserve?: {
+    bytes?: number;
+    events?: number;
+}): TraceRetentionSelection<T>;
+export declare function accumulateTraceCompactionStatistics(previous: TraceCompactionData | undefined, delta: TraceCompactionDelta): TraceCompactionData;
+export declare function traceCompactionMarkerInput(data: TraceCompactionData): {
+    data: TraceCompactionData;
+    kind: typeof TRACE_COMPACTION_KIND;
+    level: "warning";
+};
+export declare function classifyRunControlRecord(value: unknown): "pending" | "terminal" | undefined;
+export declare function runControlStatusTimestamp(record: Record<string, unknown>, status: RunControlStatus): unknown;
+export declare function computeRunControlCapacity(records: readonly unknown[]): RunControlCapacity;
+export declare function decideRunControlAdmission(input: RunControlAdmissionInput): RunControlAdmissionDecision;