@unbrained/pm-cli 2026.8.20 → 2026.8.22

package/dist/sdk/agent/tracker-preflight-contracts.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @module sdk/agent/tracker-preflight-contracts
+ *
+ * Declares and scores executable recovery for tracker filesystem preflight failures.
+ */
+/** Filesystem states distinguished by the shared tracker preflight. */
+export type PmTrackerPreflightFailureKind = "missing_root" | "settings_missing" | "not_directory" | "unreadable_root";
+/** Recovery behavior that is safe for a tracker preflight failure. */
+export type PmTrackerPreflightRecoveryKind = "initialize" | "select_directory" | "repair_permissions";
+/** Static refusal and recovery obligation for one tracker filesystem state. */
+export interface PmTrackerPreflightRecoveryContract {
+    /** Stable probe identifier used by repository gates and evidence. */
+    probe_id: string;
+    /** Filesystem state created by the executable probe. */
+    failure_kind: PmTrackerPreflightFailureKind;
+    /** Stable structured error code required from CLI and SDK transports. */
+    expected_error_code: string;
+    /** Process exit code required from the CLI transport. */
+    expected_exit_code: 1 | 2 | 3;
+    /** Safe recovery behavior for this filesystem state. */
+    recovery_kind: PmTrackerPreflightRecoveryKind;
+}
+/** Runtime evidence captured from one executable tracker preflight probe. */
+export interface PmTrackerPreflightRecoveryObservation {
+    /** Stable probe identifier from the corresponding contract. */
+    probe_id: string;
+    /** Structured error code emitted by the refusal. */
+    error_code: string;
+    /** Process exit code emitted by the refusal. */
+    exit_code: number;
+    /** Recovery behavior exercised by the probe driver. */
+    recovery_kind: PmTrackerPreflightRecoveryKind;
+    /** Tokenized retry emitted by the refusal, or an empty list when no deterministic retry is safe. */
+    suggested_retry_args: string[];
+    /** Whether the emitted retry or safe alternate-root retry executed successfully. */
+    retry_succeeded: boolean;
+    /** Whether a file-path refusal incorrectly recommended tracker initialization. */
+    unsafe_init_recommended: boolean;
+}
+/** Actionable failure emitted by the tracker preflight closure scorer. */
+export interface PmTrackerPreflightRecoveryFinding {
+    /** Stable finding code for automation and ratchets. */
+    code: "missing_probe" | "error_code_mismatch" | "exit_code_mismatch" | "recovery_kind_mismatch" | "missing_init_recovery" | "unsafe_init_recovery" | "retry_failed";
+    /** Probe that failed its recovery obligation. */
+    probe_id: string;
+    /** Human-readable explanation of the failed obligation. */
+    detail: string;
+}
+/** Aggregate executable-closure report for the tracker preflight corpus. */
+export interface PmTrackerPreflightRecoveryReport {
+    /** Whether every declared probe met its refusal and recovery contract. */
+    ok: boolean;
+    /** Number of declared tracker preflight probes. */
+    probe_count: number;
+    /** Number of probes with no findings. */
+    closed_probe_count: number;
+    /** Deterministically ordered failed obligations. */
+    findings: PmTrackerPreflightRecoveryFinding[];
+}
+/** Return defensive copies of every core tracker preflight recovery contract. */
+export declare function listTrackerPreflightRecoveryContracts(): PmTrackerPreflightRecoveryContract[];
+/** Score runtime observations against the complete tracker preflight recovery corpus. */
+export declare function scoreTrackerPreflightRecoveryClosure(observations: readonly PmTrackerPreflightRecoveryObservation[]): PmTrackerPreflightRecoveryReport;

package/dist/sdk/agent/tracker-preflight-contracts.js

@@ -0,0 +1,127 @@
+/**
+ * @module sdk/agent/tracker-preflight-contracts
+ *
+ * Declares and scores executable recovery for tracker filesystem preflight failures.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="941a11a9-f756-56b3-9dc1-8afd78bc9328")}catch(e){}}();
+const TRACKER_PREFLIGHT_RECOVERY_CONTRACTS = [
+    {
+        probe_id: "tracker-root-missing",
+        failure_kind: "missing_root",
+        expected_error_code: "tracker_root_missing",
+        expected_exit_code: 3,
+        recovery_kind: "initialize",
+    },
+    {
+        probe_id: "tracker-root-settings-missing",
+        failure_kind: "settings_missing",
+        expected_error_code: "tracker_not_initialized",
+        expected_exit_code: 3,
+        recovery_kind: "initialize",
+    },
+    {
+        probe_id: "tracker-root-not-directory",
+        failure_kind: "not_directory",
+        expected_error_code: "tracker_root_not_directory",
+        expected_exit_code: 2,
+        recovery_kind: "select_directory",
+    },
+    {
+        probe_id: "tracker-root-unreadable",
+        failure_kind: "unreadable_root",
+        expected_error_code: "tracker_root_unreadable",
+        expected_exit_code: 1,
+        recovery_kind: "repair_permissions",
+    },
+];
+/** Return defensive copies of every core tracker preflight recovery contract. */
+export function listTrackerPreflightRecoveryContracts() {
+    return TRACKER_PREFLIGHT_RECOVERY_CONTRACTS.map((contract) => ({
+        ...contract,
+    }));
+}
+function findTrackerPreflightObservationFindings(contract, observation) {
+    const findings = [];
+    if (observation.error_code !== contract.expected_error_code) {
+        findings.push({
+            code: "error_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected ${contract.expected_error_code}, received ${observation.error_code}.`,
+        });
+    }
+    if (observation.exit_code !== contract.expected_exit_code) {
+        findings.push({
+            code: "exit_code_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected exit ${contract.expected_exit_code}, received ${observation.exit_code}.`,
+        });
+    }
+    if (observation.recovery_kind !== contract.recovery_kind) {
+        findings.push({
+            code: "recovery_kind_mismatch",
+            probe_id: contract.probe_id,
+            detail: `Expected ${contract.recovery_kind}, received ${observation.recovery_kind}.`,
+        });
+    }
+    const initIndex = observation.suggested_retry_args.indexOf("init");
+    const validInitCommand = initIndex === 0 ||
+        (initIndex === 2 &&
+            observation.suggested_retry_args[0] === "--pm-path" &&
+            observation.suggested_retry_args[1]?.length > 0);
+    if (contract.recovery_kind === "initialize" && !validInitCommand) {
+        findings.push({
+            code: "missing_init_recovery",
+            probe_id: contract.probe_id,
+            detail: "Missing and uninitialized roots must emit a tokenized init retry.",
+        });
+    }
+    if (observation.unsafe_init_recommended ||
+        (contract.recovery_kind !== "initialize" &&
+            observation.suggested_retry_args.includes("init"))) {
+        findings.push({
+            code: "unsafe_init_recovery",
+            probe_id: contract.probe_id,
+            detail: "A tracker root that cannot be initialized safely must not recommend initialization.",
+        });
+    }
+    if (!observation.retry_succeeded) {
+        findings.push({
+            code: "retry_failed",
+            probe_id: contract.probe_id,
+            detail: "The emitted retry or safe alternate-root recovery did not execute successfully.",
+        });
+    }
+    return findings;
+}
+/** Score runtime observations against the complete tracker preflight recovery corpus. */
+export function scoreTrackerPreflightRecoveryClosure(observations) {
+    const observationsByProbe = new Map(observations.map((observation) => [observation.probe_id, observation]));
+    const findings = [];
+    let closedProbeCount = 0;
+    for (const contract of TRACKER_PREFLIGHT_RECOVERY_CONTRACTS) {
+        const observation = observationsByProbe.get(contract.probe_id);
+        if (observation === undefined) {
+            findings.push({
+                code: "missing_probe",
+                probe_id: contract.probe_id,
+                detail: "No runtime observation was supplied for this contract.",
+            });
+            continue;
+        }
+        const observationFindings = findTrackerPreflightObservationFindings(contract, observation);
+        findings.push(...observationFindings);
+        if (observationFindings.length === 0)
+            closedProbeCount += 1;
+    }
+    findings.sort((left, right) => left.probe_id.localeCompare(right.probe_id) ||
+        left.code.localeCompare(right.code));
+    return {
+        ok: findings.length === 0,
+        probe_count: TRACKER_PREFLIGHT_RECOVERY_CONTRACTS.length,
+        closed_probe_count: closedProbeCount,
+        findings,
+    };
+}
+//# sourceMappingURL=tracker-preflight-contracts.js.map
+//# debugId=941a11a9-f756-56b3-9dc1-8afd78bc9328

package/dist/sdk/annotations.js

@@ -4,9 +4,10 @@
  * Implements the pm annotation command command surface and its agent-facing runtime behavior.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0af9967c-ca72-563a-9518-2e68da0c0fe0")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="eac75dc5-80b4-50d2-b615-4f96edca7346")}catch(e){}}();
+import { assertInitializedTracker } from "./environment/tracker-preflight.js";
 import { readFile } from "node:fs/promises";
-import { isFileAbsentError, pathExists } from "../core/fs/fs-utils.js";
+import { isFileAbsentError } from "../core/fs/fs-utils.js";
 import { getActiveExtensionRegistrations } from "../core/extensions/index.js";
 import { resolveItemTypeRegistry } from "../core/item/type-registry.js";
 import { createStdinTokenResolver, parseCsvKv } from "../core/item/parse.js";
@@ -16,7 +17,7 @@ import { parseLimit } from "../core/shared/numeric-parsers.js";
 import { nowIso } from "../core/shared/time.js";
 import { resolveAuthor } from "../core/shared/author.js";
 import { locateItem, mutateItem, readLocatedItem, } from "../core/store/item-store.js";
-import { getSettingsPath, resolvePmRoot } from "../core/store/paths.js";
+import { resolvePmRoot } from "../core/store/paths.js";
 import { readSettings } from "../core/store/settings.js";
 /** Map transport-level `full` onto the SDK annotation history option. */
 export function normalizeAnnotationTransportOptions(options) {
@@ -215,9 +216,7 @@ function assertAnnotationMessageHasTextSource(config, options) {
 export async function runAnnotationCommand(id, options, global, config) {
     assertAnnotationMessageHasTextSource(config, options);
     const pmRoot = resolvePmRoot(process.cwd(), global.path);
-    if (!(await pathExists(getSettingsPath(pmRoot)))) {
-        throw new PmCliError(`Tracker is not initialized at ${pmRoot}. Run pm init first.`, EXIT_CODE.NOT_FOUND);
-    }
+    await assertInitializedTracker(pmRoot);
     const settings = await readSettings(pmRoot);
     const typeRegistry = resolveItemTypeRegistry(settings, getActiveExtensionRegistrations());
     const limit = parseLimit(options.limit);
@@ -399,4 +398,4 @@ function renderAnnotationResult(id, collectionKey, allEntries, limit, includeMet
     };
 }
 //# sourceMappingURL=annotations.js.map
-//# debugId=0af9967c-ca72-563a-9518-2e68da0c0fe0
+//# debugId=eac75dc5-80b4-50d2-b615-4f96edca7346

package/dist/sdk/authoring.d.ts

@@ -15,4 +15,4 @@ export { planProfileApplication, type ProfileApplicationPlan, type ProfileChange
 export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabilities, reconcileExtensionCapabilityUsage, type CollectUsedExtensionCapabilitiesOptions, type ExtensionCapabilityUsageReconciliation, } from "../core/extensions/capability-usage.js";
 export { renderExtensionSurfaceMarkdown, type ExtensionSurfaceMarkdownOptions, } from "../core/extensions/activation-summary-markdown.js";
 export { createExtensionContributionInventory, normalizeExtensionContributionInventory, } from "../core/extensions/contribution-inventory.js";
-export type { AfterCommandAffectedItem, AfterCommandHook, AfterCommandHookContext, BeforeCommandHook, BeforeCommandHookContext, BeforeMutationHook, BeforeMutationHookContext, BeforeMutationHookDecision, CommandDefinition, ExtensionCommandArgumentDefinition, CommandHandler, CommandHandlerContext, CommandHandlerResult, ExtensionCommandSdk, CommandOverride, CommandOverrideContext, ExtensionServiceName, Exporter, ExporterArtifactOutputContract, ExporterRegistrationOptions, ExtensionActivationResult, ExtensionApi, ExtensionCommandRegistry, ExtensionDeactivationFailure, ExtensionDeactivationOptions, ExtensionDeactivationResult, ExtensionDiagnostic, ExtensionContributionInventory, ExtensionDiscoveryResult, ExtensionHookRegistry, ExtensionSelfIdentity, ExtensionLoadResult, ExtensionManifest, ExtensionManifestEngines, ExtensionMutationGuardSdk, ExtensionGovernancePolicy, ExtensionPolicyOverride, ExtensionProvenanceMetadata, ExtensionRuntimePermissionDeclaration, ExtensionSearchMode, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceRegistry, FlagValueType, FlagDefinition, ImportExportContext, ImportExportRegistrationOptions, Importer, OnIndexHook, OnIndexHookContext, OnReadHook, OnReadHookContext, OnWriteHook, OnWriteHookContext, OutputRendererFormat, ParserOverride, ParserOverrideContext, ParserOverrideDelta, PreflightOverride, PreflightOverrideContext, PreflightOverrideDelta, PreflightRuntimeDecision, RegisteredExtensionExporter, RegisteredExporterArtifactOutputContract, RegisteredExtensionFlagDefinitions, RegisteredExtensionHook, RegisteredExtensionImporter, RegisteredExtensionProjectProfile, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, RendererOverride, RendererOverrideContext, SchemaFieldDefinition, SchemaItemTypeCommandOptionPolicyDefinition, SchemaItemTypeOptionDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SchemaMigrationRunContext, SchemaMigrationRunner, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderDefinition, SearchProviderHit, SearchProviderQueryContext, SearchProviderQueryResult, ServiceOverride, ServiceOverrideContext, ServiceOverrideDecision, VectorStoreAdapterDefinition, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext, VectorStoreUpsertPoint, } from "../core/extensions/loader.js";
+export type { AfterCommandAffectedItem, AfterCommandHook, AfterCommandHookContext, BeforeCommandHook, BeforeCommandHookContext, BeforeMutationHook, BeforeMutationHookContext, BeforeMutationHookDecision, CommandDefinition, ExtensionCommandArgumentDefinition, CommandHandler, CommandHandlerContext, CommandHandlerResult, ExtensionCommandSdk, CommandOverride, CommandOverrideContext, ExtensionServiceName, Exporter, ExporterArtifactOutputContract, ExporterRegistrationOptions, ExtensionActivationResult, ExtensionApi, ExtensionCommandRegistry, ExtensionDeactivationFailure, ExtensionDeactivationOptions, ExtensionDeactivationResult, ExtensionDiagnostic, ExtensionContributionInventory, ExtensionDiscoveryResult, ExtensionHookRegistry, ExtensionSelfIdentity, ExtensionLoadResult, ExtensionManifest, ExtensionManifestEngines, ExtensionMutationGuardSdk, ExtensionGovernancePolicy, ExtensionPolicyOverride, ExtensionProvenanceMetadata, ExtensionRuntimePermissionDeclaration, ExtensionSearchMode, ExtensionParserRegistry, ExtensionPreflightRegistry, ExtensionRegistrationRegistry, ExtensionRendererRegistry, ExtensionServiceRegistry, FlagValueType, FlagDefinition, ImportExportContext, ImportExportRegistrationOptions, Importer, OnIndexHook, OnIndexHookContext, OnReadHook, OnReadHookContext, OnWriteHook, OnWriteHookContext, OutputRendererFormat, ParserOverride, ParserOverrideContext, ParserOverrideDelta, PreflightOverride, PreflightOverrideContext, PreflightOverrideDelta, PreflightRuntimeDecision, RegisteredExtensionExporter, RegisteredExporterArtifactOutputContract, RegisteredExtensionFlagDefinitions, RegisteredExtensionHook, RegisteredExtensionImporter, RegisteredExtensionProjectProfile, RegisteredExtensionSchemaMigrationDefinition, RegisteredExtensionSearchProvider, RegisteredExtensionServiceOverride, RegisteredExtensionVectorStoreAdapter, RendererOverride, RendererOverrideContext, SchemaFieldDefinition, SchemaItemTypeCommandOptionPolicyDefinition, SchemaItemTypeOptionDefinition, SchemaItemTypeDefinition, SchemaMigrationDefinition, SchemaMigrationRunContext, SchemaMigrationRunner, SearchProviderEmbedBatchContext, SearchProviderEmbedContext, SearchProviderDefinition, SearchProviderHit, SearchProviderQueryContext, SearchProviderQueryResult, ServiceOverride, ServiceOverrideContext, ServiceOverrideDecision, ServiceOverrideOwnership, VectorStoreAdapterDefinition, VectorStoreDeleteContext, VectorStoreQueryContext, VectorStoreQueryHit, VectorStoreUpsertContext, VectorStoreUpsertPoint, } from "../core/extensions/loader.js";

package/dist/sdk/authoring.js

@@ -4,7 +4,7 @@
  * Provides the focused extension and package authoring surface.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="6260572c-1496-58ef-9377-0825f4183bc6")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="bca95ba2-258c-5be2-8428-dcb8dbc87ef0")}catch(e){}}();
 export * from "./compose.js";
 export * from "./define.js";
 export * from "./extension-contracts.js";
@@ -18,4 +18,4 @@ export { EXTENSION_CAPABILITY_REGISTRATION_SURFACES, collectUsedExtensionCapabil
 export { renderExtensionSurfaceMarkdown, } from "../core/extensions/activation-summary-markdown.js";
 export { createExtensionContributionInventory, normalizeExtensionContributionInventory, } from "../core/extensions/contribution-inventory.js";
 //# sourceMappingURL=authoring.js.map
-//# debugId=6260572c-1496-58ef-9377-0825f4183bc6
+//# debugId=bca95ba2-258c-5be2-8428-dcb8dbc87ef0

package/dist/sdk/cli-contracts/agent-output-contracts.d.ts

@@ -6,6 +6,59 @@ export type PmOutputDegradationStep = (typeof PM_OUTPUT_DEGRADATION_STEPS)[numbe
 export declare const PM_OUTPUT_BUDGET_CLASSES: readonly ["mutation", "read", "discovery", "governance"];
 /** Restricts command-output budget classes. */
 export type PmOutputBudgetClass = (typeof PM_OUTPUT_BUDGET_CLASSES)[number];
+/** Stable diagnostic families that require independent output ceilings. */
+export declare const PM_DIAGNOSTIC_OUTPUT_CLASSES: readonly ["error", "warning", "validation_summary", "recovery_bundle"];
+/** Restricts diagnostic budget selection to declared families. */
+export type PmDiagnosticOutputClass = (typeof PM_DIAGNOSTIC_OUTPUT_CLASSES)[number];
+/** Deterministic diagnostic degradation stages, from richest to smallest. */
+export declare const PM_DIAGNOSTIC_DEGRADATION_STEPS: readonly ["full", "omit_explanation", "limit_collections", "compact_recovery", "action_only"];
+/** Restricts diagnostic degradation receipts to declared stages. */
+export type PmDiagnosticDegradationStep = (typeof PM_DIAGNOSTIC_DEGRADATION_STEPS)[number];
+/** Declares one diagnostic family's text and JSON token ceilings. */
+export interface PmDiagnosticOutputBudgetContract {
+    /** Diagnostic family governed by this contract. */
+    diagnostic_class: PmDiagnosticOutputClass;
+    /** Default ceiling by rendered transport. */
+    default_max_estimated_tokens_by_format: Readonly<{
+        text: number;
+        json: number;
+    }>;
+    /** Smallest explicit ceiling accepted by the projector. */
+    minimum_max_estimated_tokens: number;
+    /** Ordered degradation policy applied when the ceiling binds. */
+    degradation_ladder: readonly PmDiagnosticDegradationStep[];
+    /** Paths whose first actionable value must survive degradation. */
+    corrective_action_paths: readonly string[];
+    /** Stable estimate used by gates and SDK consumers. */
+    token_estimate: "ceil(utf8_bytes / 4)";
+}
+/** Machine-readable disclosure attached to a projected diagnostic. */
+export interface PmDiagnosticOutputReceipt {
+    /** Diagnostic family whose contract bound the output. */
+    diagnostic_class: PmDiagnosticOutputClass;
+    /** Rendered transport measured by the projector. */
+    format: "json" | "text";
+    /** Effective estimated-token ceiling. */
+    budget: number;
+    /** Whether the caller supplied the ceiling or used the declaration. */
+    budget_source: "default" | "explicit";
+    /** Estimate before diagnostic degradation. */
+    original_estimated_tokens: number;
+    /** Exact estimate of the returned projection. */
+    estimated_tokens: number;
+    /** Whether one or more fields were removed or compacted. */
+    truncated: boolean;
+    /** Applied stages in contract order. */
+    degradation_steps: PmDiagnosticDegradationStep[];
+    /** Top-level fields removed from the original diagnostic. */
+    omitted_fields: string[];
+    /** Additional omitted fields not named individually in a bounded receipt. */
+    omitted_fields_overflow_count?: number;
+}
+/** JSON diagnostic after binding it to a declared output contract. */
+export type PmProjectedDiagnostic<TDiagnostic extends object> = Partial<TDiagnostic> & Pick<TDiagnostic, Extract<keyof TDiagnostic, "code" | "required">> & {
+    diagnostic_output?: PmDiagnosticOutputReceipt;
+};
 /** Describes one command's default agent-output budget and degradation policy. */
 export interface PmCommandOutputBudgetContract {
     /** Canonical or compatibility command name. */
@@ -26,6 +79,8 @@ export interface PmCommandOutputBudgetContract {
     /** Stable estimate used by gates and SDK consumers. */
     token_estimate: "ceil(utf8_bytes / 4)";
 }
+/** Public default contract for every diagnostic family. */
+export declare const PM_DIAGNOSTIC_OUTPUT_BUDGET_CONTRACTS: PmDiagnosticOutputBudgetContract[];
 /** Infer the conservative workload class for a core or package command. */
 export declare function inferPmOutputBudgetClass(command: string): PmOutputBudgetClass;
 /** Build the generated default budget for a core or package command. */
@@ -48,3 +103,25 @@ export declare function resolvePmCommandOutputBudget(command: string, options?:
 }): PmCommandOutputBudgetContract | null;
 /** Estimate conservative token usage from UTF-8 output bytes. */
 export declare function estimatePmOutputTokens(utf8Bytes: number): number;
+/** Resolve the binding output contract for one diagnostic family. */
+export declare function resolvePmDiagnosticOutputBudget(diagnosticClass: PmDiagnosticOutputClass): PmDiagnosticOutputBudgetContract;
+/**
+ * Bind a JSON diagnostic to its declared ceiling while preserving the first
+ * corrective action and reporting every top-level omission.
+ */
+export declare function projectPmDiagnosticOutput<TDiagnostic extends object>(diagnostic: TDiagnostic, options?: {
+    diagnosticClass?: PmDiagnosticOutputClass;
+    maxEstimatedTokens?: number;
+}): PmProjectedDiagnostic<TDiagnostic>;
+/** Text diagnostic together with the same measured receipt used by JSON. */
+export interface PmProjectedTextDiagnostic {
+    /** Rendered action-first diagnostic. */
+    output: string;
+    /** Binding diagnostic budget receipt. */
+    diagnostic_output: PmDiagnosticOutputReceipt;
+}
+/** Bind human-readable diagnostics without ever truncating the corrective action away. */
+export declare function projectPmDiagnosticText(output: string, correctiveAction: string, options?: {
+    diagnosticClass?: PmDiagnosticOutputClass;
+    maxEstimatedTokens?: number;
+}): PmProjectedTextDiagnostic;