@unbrained/pm-cli 2026.9.2 → 2026.9.4

package/dist/sdk/context-usage.js

@@ -6,7 +6,7 @@
  * intents; it never enters item history and is safe to delete or rebuild.
  */
 
-!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]="5f4ccd28-a001-54aa-8378-893025c69b96")}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]="997a09a2-cf0c-5384-b457-d9627d465b71")}catch(e){}}();
 import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, readFile, rename, stat, writeFile, } from "node:fs/promises";
 import path from "node:path";
@@ -16,6 +16,154 @@ const DEFAULT_RETENTION_DAYS = 30;
 const DAY_MS = 86_400_000;
 const DEFAULT_COMPACTION_BYTES = 262_144;
 const CONTEXT_USAGE_LOCK_ID = "context-usage-ledger";
+const CONTEXT_USAGE_SERVING_RECEIPT = Symbol.for("@unbrained/pm-cli/context-usage-serving-receipt");
+function asObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** Attach a JSON-invisible serving receipt to a result for later egress. */
+export function attachContextUsageServingReceipt(result, receipt) {
+    const record = asObjectRecord(result);
+    if (record !== null && receipt !== null) {
+        record[CONTEXT_USAGE_SERVING_RECEIPT] = receipt;
+    }
+}
+/** Copy an attached serving receipt across a result projection boundary. */
+export function propagateContextUsageServingReceipt(source, target) {
+    const sourceRecord = asObjectRecord(source);
+    const targetRecord = asObjectRecord(target);
+    const receipt = sourceRecord?.[CONTEXT_USAGE_SERVING_RECEIPT];
+    if (targetRecord !== null && receipt !== undefined) {
+        targetRecord[CONTEXT_USAGE_SERVING_RECEIPT] = receipt;
+    }
+}
+function receiptFromResult(result) {
+    return (asObjectRecord(result)?.[CONTEXT_USAGE_SERVING_RECEIPT] ?? null);
+}
+function resultReceiptSaysOmitted(result) {
+    const record = asObjectRecord(result);
+    for (const key of ["read_output", "context_intent"]) {
+        const receipt = asObjectRecord(record?.[key]);
+        if (receipt?.result_omitted === true)
+            return true;
+    }
+    return false;
+}
+function addContextUsageId(ids, value) {
+    if (typeof value === "string" && value.trim().length > 0) {
+        ids.add(value.trim());
+    }
+}
+function addContextUsageDirectRows(ids, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const row of value) {
+        addContextUsageId(ids, asObjectRecord(row)?.id);
+    }
+}
+function addContextUsageIdList(ids, value) {
+    if (!Array.isArray(value))
+        return;
+    for (const itemId of value)
+        addContextUsageId(ids, itemId);
+}
+function collectNextResultItemIds(record, ids) {
+    const rows = [
+        ...(asObjectRecord(record.recommended) === null
+            ? []
+            : [record.recommended]),
+        ...(Array.isArray(record.ready) ? record.ready : []),
+        ...(Array.isArray(record.decision_needed) ? record.decision_needed : []),
+        ...(Array.isArray(record.blocked) ? record.blocked : []),
+        ...(Array.isArray(record.held_by_others) ? record.held_by_others : []),
+    ];
+    for (const value of rows) {
+        const row = asObjectRecord(value);
+        addContextUsageId(ids, row?.id);
+        for (const blocker of Array.isArray(row?.blockers) ? row.blockers : []) {
+            addContextUsageId(ids, asObjectRecord(blocker)?.id);
+        }
+        for (const unblockedId of Array.isArray(row?.unblocks)
+            ? row.unblocks
+            : []) {
+            addContextUsageId(ids, unblockedId);
+        }
+    }
+}
+function collectContextResultItemIds(record, ids) {
+    for (const key of [
+        "high_level",
+        "low_level",
+        "blocked_fallback",
+        "recently_created",
+        "unparented",
+        "activity",
+        "progress",
+        "blockers",
+        "staleness",
+    ]) {
+        addContextUsageDirectRows(ids, record[key]);
+    }
+    for (const value of Array.isArray(record.blockers)
+        ? record.blockers
+        : []) {
+        addContextUsageId(ids, asObjectRecord(value)?.blocked_by);
+    }
+    collectContextNestedItemIds(record, ids);
+}
+function collectContextNestedItemIds(record, ids) {
+    for (const value of Array.isArray(record.hierarchy)
+        ? record.hierarchy
+        : []) {
+        const node = asObjectRecord(value);
+        addContextUsageId(ids, node?.id);
+        addContextUsageDirectRows(ids, node?.children);
+    }
+    for (const key of ["files", "workload"]) {
+        for (const value of Array.isArray(record[key]) ? record[key] : []) {
+            addContextUsageIdList(ids, asObjectRecord(value)?.items);
+        }
+    }
+    const agenda = asObjectRecord(record.agenda);
+    for (const value of Array.isArray(agenda?.events) ? agenda.events : []) {
+        addContextUsageId(ids, asObjectRecord(value)?.item_id);
+    }
+    const tests = asObjectRecord(record.tests);
+    addContextUsageIdList(ids, tests?.items_failing);
+}
+/**
+ * Collect every item identifier visible in a final context or next result.
+ * The traversal is shape-aware so summary counters and unrelated identifier
+ * fields cannot enter the privacy-minimal usage ledger.
+ */
+export function collectContextUsageDeliveredItemIds(result, surface) {
+    const record = asObjectRecord(result);
+    if (record === null || resultReceiptSaysOmitted(result))
+        return [];
+    const ids = new Set();
+    if (surface === "next") {
+        collectNextResultItemIds(record, ids);
+    }
+    else {
+        collectContextResultItemIds(record, ids);
+    }
+    return [...ids];
+}
+/** Resolve and append one post-egress decision carried by a context result. */
+export async function finalizeContextUsageDelivery(options) {
+    const receipt = receiptFromResult(options.result);
+    if (receipt === null)
+        return false;
+    const resultOmitted = resultReceiptSaysOmitted(options.result);
+    await recordContextUsageDelivery({
+        pmRoot: options.pmRoot,
+        receipt,
+        deliveredItemIds: collectContextUsageDeliveredItemIds(options.result, receipt.surface),
+        resultOmitted,
+    });
+    return true;
+}
 /** Named validation failure emitted by context-usage SDK inputs. */
 export class ContextUsageValidationError extends TypeError {
     /** Stable machine-readable error code for package and CLI hosts. */
@@ -61,7 +209,7 @@ async function readEvents(options) {
         return [];
     }
 }
-async function appendEvents(options, events) {
+async function appendEvents(options, events, deliveryServeId) {
     const maxEvents = options.maxEvents ?? DEFAULT_MAX_EVENTS;
     const retentionDays = options.retentionDays ?? DEFAULT_RETENTION_DAYS;
     if (!Number.isInteger(maxEvents) ||
@@ -75,6 +223,10 @@ async function appendEvents(options, events) {
     const releaseLock = await acquireLock(options.pmRoot, CONTEXT_USAGE_LOCK_ID, 30, `context-usage:${process.pid}`, false, false, 3_000);
     try {
         await mkdir(runtimeDirectory, { recursive: true });
+        if (deliveryServeId !== undefined &&
+            (await readEvents(options)).some((event) => event.kind === "delivery" && event.serve_id === deliveryServeId)) {
+            return;
+        }
         await appendFile(target, events.map((event) => `${JSON.stringify(event)}\n`).join(""), "utf8");
         const customBounds = options.maxEvents !== undefined || options.retentionDays !== undefined;
         if (!customBounds && (await stat(target)).size <= DEFAULT_COMPACTION_BYTES)
@@ -93,21 +245,70 @@ async function appendEvent(options, event) {
 }
 /** Records a propensity-complete context/next serving event. */
 export async function recordContextUsageServing(options) {
-    if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
-        options.enabled === false)
-        return;
+    if ([
+        process.env.PM_CONTEXT_USAGE_DISABLED === "1",
+        options.enabled === false,
+    ].includes(true))
+        return null;
     if (!options.author.trim() ||
         options.rows.some((row) => !row.id.trim() || !Number.isInteger(row.rank) || row.rank < 1)) {
         throw new ContextUsageValidationError("Context usage serving requires an author and valid ranked rows");
     }
+    const normalizedRows = options.rows.map((row) => ({
+        ...row,
+        id: row.id.trim(),
+    }));
+    if (new Set(normalizedRows.map((row) => row.id)).size !== normalizedRows.length) {
+        throw new ContextUsageValidationError("Context usage serving requires unique normalized row ids");
+    }
+    const receipt = {
+        serve_id: randomUUID(),
+        author: options.author.trim(),
+        surface: options.surface,
+        rows: normalizedRows,
+    };
     await appendEvent(options, {
         kind: "serve",
+        schema_version: 2,
+        serve_id: receipt.serve_id,
         at: resolveNow(options).iso,
         author: options.author.trim(),
         surface: options.surface,
         profile: options.profile.trim() || "balanced",
-        rows: options.rows,
+        rows: receipt.rows.map((row) => ({ ...row })),
+        result_omitted: false,
+        packed_item_ids: receipt.rows
+            .filter((row) => row.included)
+            .map((row) => row.id),
     });
+    return receipt;
+}
+/** Append the exact post-egress delivery decision for one serving receipt. */
+export async function recordContextUsageDelivery(options) {
+    if (options.receipt === null ||
+        process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
+        options.enabled === false) {
+        return;
+    }
+    const rankedIds = new Set(options.receipt.rows.map((row) => row.id));
+    const deliveredItemIds = [
+        ...new Set(options.deliveredItemIds.map((id) => id.trim())),
+    ];
+    if (deliveredItemIds.some((id) => id.length === 0 || !rankedIds.has(id)) ||
+        (options.resultOmitted && deliveredItemIds.length > 0)) {
+        throw new ContextUsageValidationError("Context usage delivery requires emitted ranked ids and zero ids for an omitted result");
+    }
+    const delivery = {
+        kind: "delivery",
+        schema_version: 2,
+        serve_id: options.receipt.serve_id,
+        at: resolveNow(options).iso,
+        author: options.receipt.author,
+        surface: options.receipt.surface,
+        result_omitted: options.resultOmitted,
+        delivered_item_ids: deliveredItemIds,
+    };
+    await appendEvents(options, [delivery], delivery.serve_id);
 }
 /** Records one subsequent item read or mutation outcome. */
 export async function recordContextUsageTouch(options) {
@@ -165,6 +366,18 @@ function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
         time >= servedAt &&
         time - servedAt <= horizonMs)?.time;
 }
+function firstDeliveriesByServeId(events, author) {
+    const deliveries = new Map();
+    for (const event of events) {
+        if (event.kind === "delivery" &&
+            event.schema_version === 2 &&
+            event.author === author &&
+            !deliveries.has(event.serve_id)) {
+            deliveries.set(event.serve_id, event);
+        }
+    }
+    return deliveries;
+}
 /**
  * Derives decayed served-then-touched affinity. A small exploration floor keeps
  * ignored and unseen items eligible, preventing a popularity feedback lock-in.
@@ -172,26 +385,41 @@ function findTouchTimeInHorizon(touches, itemId, servedAt, horizonMs) {
 export async function readContextUsageAffinity(options) {
     if (process.env.PM_CONTEXT_USAGE_DISABLED === "1" ||
         options.enabled === false)
-        return { affinity: {}, positive_judgments: 0, serving_events: 0 };
+        return {
+            affinity: {},
+            positive_judgments: 0,
+            serving_events: 0,
+            untrusted_serving_events: 0,
+        };
     const events = await readEvents(options);
     const now = resolveNow(options).ms;
     const horizonMs = (options.horizonHours ?? 24) * 3_600_000;
-    if (!Number.isFinite(horizonMs) || horizonMs <= 0)
+    if (![Number.isFinite(horizonMs), horizonMs > 0].every(Boolean))
         throw new ContextUsageValidationError("Context usage horizonHours must be positive");
     const author = options.author.trim();
     const touches = events
-        .filter((event) => event.kind === "touch" && event.author === author)
+        .filter((event) => event.kind === "touch")
+        .filter((event) => event.author === author)
         .map((entry) => ({ entry, time: Date.parse(entry.at) }));
     const scores = new Map();
     let servingEvents = 0;
+    let untrustedServingEvents = 0;
     let positiveJudgments = 0;
-    for (const event of events) {
-        if (event.kind !== "serve" || event.author !== author)
-            continue;
+    const deliveries = firstDeliveriesByServeId(events, author);
+    events
+        .filter((event) => event.kind === "serve")
+        .filter((event) => event.author === author)
+        .forEach((event) => {
+        if (![event.schema_version === 2, Boolean(event.serve_id)].every(Boolean)) {
+            untrustedServingEvents += 1;
+            return;
+        }
         servingEvents += 1;
         const servedAt = Date.parse(event.at);
+        const delivery = deliveries.get(event.serve_id);
+        const deliveredIds = new Set(delivery?.delivered_item_ids ?? []);
         for (const row of event.rows) {
-            if (!row.included)
+            if (!deliveredIds.has(row.id))
                 continue;
             const touchTime = findTouchTimeInHorizon(touches, row.id, servedAt, horizonMs);
             if (touchTime === undefined)
@@ -200,17 +428,18 @@ export async function readContextUsageAffinity(options) {
             const ageDays = Math.max(0, (now - touchTime) / DAY_MS);
             scores.set(row.id, (scores.get(row.id) ?? 0) + Math.exp(-ageDays / 14));
         }
-    }
+    });
     const maximum = Math.max(0, ...scores.values());
     const affinity = Object.fromEntries([...scores.entries()].map(([id, score]) => [
         id,
-        0.05 + 0.95 * (maximum > 0 ? score / maximum : 0),
+        maximum === 0 ? 0.05 : 0.05 + (0.95 * score) / maximum,
     ]));
     return {
         affinity,
         positive_judgments: positiveJudgments,
         serving_events: servingEvents,
+        untrusted_serving_events: untrustedServingEvents,
     };
 }
 //# sourceMappingURL=context-usage.js.map
-//# debugId=5f4ccd28-a001-54aa-8378-893025c69b96
+//# debugId=997a09a2-cf0c-5384-b457-d9627d465b71

package/dist/sdk/environment/agent-environment.d.ts

@@ -0,0 +1,296 @@
+import { type WorkspaceRecipe } from "../workspace-recipe.js";
+/** Schema identifier for a portable observation contract. */
+export declare const PM_OBSERVATION_SCHEMA: "pm.agent-observation/v1";
+/** Schema identifier for a deterministic verdict contract. */
+export declare const PM_VERDICT_SCHEMA: "pm.agent-verdict/v1";
+/** Schema identifier for a bounded agent-environment episode. */
+export declare const PM_EPISODE_SCHEMA: "pm.agent-episode/v1";
+/** A JSON-compatible object used as immutable recorded workspace state. */
+export type RecordedStateObject = Readonly<Record<string, unknown>>;
+/** One declared read and its guaranteed token ceiling. */
+export interface ObservationReadDeclaration {
+    /** Public SDK or CLI command name used to collect the read. */
+    command: string;
+    /** Maximum tokens this read may consume. */
+    budget_tokens: number;
+}
+/** Emitted-byte calibration for a representative observation corpus. */
+export interface ObservationCalibration {
+    /** Stable measurement basis; serialized payload bytes are authoritative. */
+    basis: "emitted_bytes";
+    /** Historical emitted-byte measurements used to calibrate expectations. */
+    samples: readonly number[];
+    /** Expected serialized payload size before an observation is served. */
+    expected_emitted_bytes: number;
+    /** Accepted drift around the expected emitted-byte measurement. */
+    tolerance_bytes: number;
+}
+/** Declares whether observation cost varies with corpus size. */
+export type ObservationCorpusDependence = {
+    readonly kind: "independent";
+} | {
+    readonly kind: "bounded";
+    readonly dimension: string;
+    readonly maximum: number;
+};
+/** One ordered disclosure tier in an observation degradation ladder. */
+export interface ObservationTier {
+    /** Stable tier identity included in every observation receipt. */
+    id: string;
+    /** Maximum tokens this tier is permitted to emit. */
+    max_tokens: number;
+    /** Dot-separated recorded-state fields disclosed by the tier. */
+    fields: readonly string[];
+}
+/** Portable declaration for a bounded, calibrated observation. */
+export interface ObservationContract {
+    /** Versioned schema identity. */
+    schema: typeof PM_OBSERVATION_SCHEMA;
+    /** Stable contract identity. */
+    id: string;
+    /** Positive contract revision. */
+    version: number;
+    /** Reads whose ceilings form the guaranteed collection cost. */
+    reads: readonly ObservationReadDeclaration[];
+    /** Emitted-byte calibration visible before collection starts. */
+    calibration: ObservationCalibration;
+    /** Explicit corpus-size dependence of the cost model. */
+    corpus_dependence: ObservationCorpusDependence;
+    /** Ordered richest-to-smallest degradation ladder. */
+    tiers: readonly ObservationTier[];
+}
+/** Pre-call observation-cost description available to schedulers. */
+export interface ObservationCostDescription {
+    /** Stable observation identity. */
+    contract_id: string;
+    /** Observation revision. */
+    contract_version: number;
+    /** Sum of all declared collection ceilings. */
+    guaranteed_ceiling_tokens: number;
+    /** Calibrated expected serialized payload size. */
+    expected_emitted_bytes: number;
+    /** Conservative token estimate derived from emitted bytes. */
+    expected_tokens: number;
+    /** Accepted emitted-byte calibration drift. */
+    tolerance_bytes: number;
+    /** Stable calibration basis. */
+    calibration_basis: "emitted_bytes";
+    /** Declared corpus-size dependence. */
+    corpus_dependence: ObservationCorpusDependence;
+}
+/** Audit receipt emitted for every served or refused observation. */
+export interface ObservationReceipt {
+    /** Stable observation identity. */
+    contract_id: string;
+    /** Observation revision. */
+    contract_version: number;
+    /** Tier whose payload was returned, or null after truthful refusal. */
+    served_tier: string | null;
+    /** Whether a smaller tier was attempted or served. */
+    degraded: boolean;
+    /** Tier identities evaluated in deterministic order. */
+    attempted_tiers: readonly string[];
+    /** Exact serialized payload bytes, or null when nothing was served. */
+    emitted_bytes: number | null;
+    /** Conservative token estimate, or null when nothing was served. */
+    estimated_tokens: number | null;
+    /** Stable measurement basis. */
+    calibration_basis: "emitted_bytes";
+}
+/** Successful bounded observation with its explicit receipt. */
+export interface ServedObservation<T> {
+    /** Discriminator for a payload-bearing response. */
+    status: "served";
+    /** Payload produced by the declared tier. */
+    payload: T;
+    /** Cost and degradation evidence. */
+    receipt: ObservationReceipt;
+}
+/** Refusal returned when no declared tier can fit the caller's ceiling. */
+export interface RefusedObservation {
+    /** Discriminator for a payload-free refusal. */
+    status: "refused";
+    /** Stable reason callers can route without parsing prose. */
+    reason: "no_declared_tier_fits_budget";
+    /** Cost and degradation evidence. */
+    receipt: ObservationReceipt;
+}
+/** Complete outcome of attempting one declared observation. */
+export type ObservationResult<T> = ServedObservation<T> | RefusedObservation;
+/** Caller-imposed ceiling for one observation response. */
+export interface ObservationRequest {
+    /** Maximum response tokens accepted by the caller. */
+    budget_tokens: number;
+}
+/** Predicate supported by the versioned total-verdict interpreter. */
+export type VerdictPredicate = {
+    readonly id: string;
+    readonly kind: "field_equals";
+    readonly path: string;
+    readonly expected: unknown;
+} | {
+    readonly id: string;
+    readonly kind: "field_present";
+    readonly path: string;
+} | {
+    readonly id: string;
+    readonly kind: "field_absent";
+    readonly path: string;
+};
+/** Declarative composition applied to predicate outcomes. */
+export interface VerdictComposition {
+    /** Whether every or at least one referenced predicate must satisfy. */
+    operator: "all" | "any";
+    /** Ordered predicate identities evaluated by the total verdict. */
+    predicate_ids: readonly string[];
+}
+/** Portable named and versioned total-verdict declaration. */
+export interface VerdictContract {
+    /** Versioned schema identity. */
+    schema: typeof PM_VERDICT_SCHEMA;
+    /** Stable contract identity. */
+    id: string;
+    /** Positive contract revision. */
+    version: number;
+    /** Predicates evaluated exclusively over recorded state. */
+    predicates: readonly VerdictPredicate[];
+    /** Explicit deterministic predicate composition. */
+    composition: VerdictComposition;
+}
+/** Recorded state and stable snapshot identity supplied by an adapter. */
+export interface WorkspaceRecordedState {
+    /** Stable identity of the exact state being evaluated. */
+    snapshot_id: string;
+    /** Recorded, JSON-compatible project state. */
+    state: RecordedStateObject;
+}
+/** Per-predicate evidence in a deterministic total verdict. */
+export interface PredicateVerdict {
+    /** Declared predicate identity. */
+    id: string;
+    /** Whether the predicate is satisfied by recorded state. */
+    outcome: "satisfied" | "violated";
+    /** Snapshot-qualified JSON pointer to the inspected field. */
+    evidence_pointer: string;
+    /** Hash of the observed value without duplicating potentially private data. */
+    evidence_digest: string;
+}
+/** Total, reproducible result produced by a verdict contract. */
+export interface VerdictResult {
+    /** Stable verdict identity. */
+    contract_id: string;
+    /** Verdict revision. */
+    contract_version: number;
+    /** Exact recorded-state snapshot evaluated. */
+    snapshot_id: string;
+    /** Total outcome, including an explicit empty-contract state. */
+    outcome: "satisfied" | "violated" | "not_applicable";
+    /** Satisfied fraction, or null when no predicates are declared. */
+    score: number | null;
+    /** Explicitly separates evaluation from reward or learning signals. */
+    policy: "verdict_only_no_reward";
+    /** Stable explanation for a not-applicable verdict. */
+    reason?: "no_predicates_declared";
+    /** Ordered predicate evidence. */
+    predicates: readonly PredicateVerdict[];
+}
+/** Hard limits enforced within one isolated episode. */
+export interface EpisodeLimits {
+    /** Maximum ordinary project-management actions. */
+    max_actions: number;
+    /** Maximum observations, including the close-time grading read. */
+    max_observations: number;
+    /** Per-observation response ceiling. */
+    max_tokens_per_observation: number;
+}
+/** Portable specification shared by evaluation and training harnesses. */
+export interface EpisodeSpecification {
+    /** Versioned schema identity. */
+    schema: typeof PM_EPISODE_SCHEMA;
+    /** Stable episode identity and session provenance key. */
+    id: string;
+    /** Positive episode revision. */
+    version: number;
+    /** Consumer intent without coupling the runtime to a training framework. */
+    mode: "benchmark" | "evaluation" | "training" | "scale_transfer";
+    /** Deterministic workspace construction recipe. */
+    recipe: WorkspaceRecipe;
+    /** Canonical pm items that define the task set. */
+    task_item_ids: readonly string[];
+    /** State fields that observations may disclose. */
+    observable_fields: readonly string[];
+    /** Grading-only fields that must never enter observations. */
+    withheld_fields: readonly string[];
+    /** Bounded observation declaration. */
+    observation: ObservationContract;
+    /** Recorded-state verdict declaration. */
+    verdict: VerdictContract;
+    /** Hard action and observation limits. */
+    limits: EpisodeLimits;
+}
+/** Reset receipt returned by an episode adapter. */
+export interface EpisodeResetReceipt {
+    /** Adapter-defined isolated workspace identity. */
+    workspace_id: string;
+    /** Stable state identity after reset. */
+    state_id: string;
+}
+/** Action receipt returned by an episode adapter. */
+export interface EpisodeActionReceipt<TOutput> {
+    /** Stable state identity after the action. */
+    state_id: string;
+    /** Adapter-defined ordinary command result. */
+    output: TOutput;
+}
+/** Host boundary for ordinary pm SDK actions and recorded-state reads. */
+export interface EpisodeRuntimeAdapter<TAction, TOutput = unknown> {
+    /** Construct a fresh isolated workspace using the declared recipe. */
+    reset(recipe: WorkspaceRecipe): Promise<EpisodeResetReceipt>;
+    /** Execute one ordinary action, normally by calling `PmClient.run`. */
+    execute(action: TAction): Promise<EpisodeActionReceipt<TOutput>>;
+    /** Read immutable grading state from the workspace system of record. */
+    readRecordedState(): Promise<WorkspaceRecordedState>;
+}
+/** One deterministic entry in a portable episode trajectory. */
+export interface EpisodeTrajectoryEntry {
+    /** Monotonic event number within the isolated episode. */
+    sequence: number;
+    /** Stable event classification. */
+    kind: "reset" | "observation" | "action" | "verdict" | "close";
+    /** Snapshot, state, or observation tier associated with the event. */
+    state_id: string;
+}
+/** Closed episode evidence without reward or framework-specific shaping. */
+export interface ClosedEpisode {
+    /** Deterministic total verdict. */
+    verdict: VerdictResult;
+    /** Complete bounded trajectory. */
+    trajectory: readonly EpisodeTrajectoryEntry[];
+    /** Explicitly absent to prevent verdicts from becoming reward signals. */
+    reward?: never;
+}
+/** Isolated runtime returned for one declared agent episode. */
+export interface PmEpisodeSession<TAction, TOutput> {
+    /** Observe recorded state through the declared disclosure ladder. */
+    observe(): Promise<ObservationResult<RecordedStateObject>>;
+    /** Execute one bounded ordinary project-management action. */
+    step(action: TAction): Promise<EpisodeActionReceipt<TOutput>>;
+    /** Evaluate the current recorded state without closing the session. */
+    score(): Promise<VerdictResult>;
+    /** Evaluate and close the episode, returning immutable evidence. */
+    close(): Promise<ClosedEpisode>;
+}
+/** Validate, clone, and freeze a portable observation declaration. */
+export declare function defineObservationContract(declaration: ObservationContract): ObservationContract;
+/** Describe guaranteed and calibrated observation cost before collection. */
+export declare function describeObservationCost(contract: ObservationContract): ObservationCostDescription;
+/** Serve the richest declared tier that fits both caller and tier ceilings. */
+export declare function serveDeclaredObservation<T>(contract: ObservationContract, collect: (tier: ObservationTier) => Promise<T>, request: ObservationRequest): Promise<ObservationResult<T>>;
+/** Validate, clone, and freeze a portable total-verdict declaration. */
+export declare function defineVerdictContract(declaration: VerdictContract): VerdictContract;
+/** Evaluate a total verdict exclusively from one immutable recorded snapshot. */
+export declare function evaluateVerdictContract(contract: VerdictContract, recorded: WorkspaceRecordedState): VerdictResult;
+/** Validate, clone, and freeze a portable episode specification. */
+export declare function defineEpisodeSpecification(declaration: EpisodeSpecification): EpisodeSpecification;
+/** Open one isolated, deterministic episode around an adapter's ordinary actions. */
+export declare function openPmEpisode<TAction, TOutput = unknown>(specification: EpisodeSpecification, adapter: EpisodeRuntimeAdapter<TAction, TOutput>): Promise<PmEpisodeSession<TAction, TOutput>>;