@farmslot/protocol 0.21.0 → 0.26.0

package/dist/contracts/pressure-admission.d.ts

@@ -0,0 +1,175 @@
+import type { ProcessAttributionConfidence, ProcessOwnershipClass } from '../rpc/resources.js';
+import type { HostPressureAdmissionMode } from './runtime-capabilities.js';
+/**
+ * Dispatch admission has no queue: a machine under sustained pressure either
+ * accepts new dispatches or refuses them. Same vocabulary as the capability
+ * side so one word means one thing across both gates.
+ */
+export type DispatchPressureAdmissionMode = Exclude<HostPressureAdmissionMode, 'queue'>;
+export declare const DISPATCH_PRESSURE_ADMISSION_MODES: readonly DispatchPressureAdmissionMode[];
+/** Machine-level admission state derived from the bounded pressure sample
+ * ring. `disabled` means the gateway-owned switch is off — the DEFAULT: the
+ * dispatch is admitted whatever the evidence says, while the evidence itself
+ * is still evaluated and carried as an advisory, and sampling/history/charts
+ * continue. */
+export type PressureAdmissionState = 'green' | 'transient' | 'sustained-critical' | 'unavailable' | 'stale' | 'override' | 'disabled';
+/** Stable machine-readable rejection codes. Never rename — clients and
+ * operators key automation off these. */
+export declare const PRESSURE_ADMISSION_REJECTION_CODES: readonly ["PRESSURE_SUSTAINED_CRITICAL", "PRESSURE_EVIDENCE_UNAVAILABLE", "PRESSURE_EVIDENCE_STALE", "PRESSURE_PREVIEW_STALE", "PRESSURE_OVERRIDE_STALE", "PRESSURE_OVERRIDE_MISMATCH", "PRESSURE_OVERRIDE_REASON_REQUIRED", "PRESSURE_OVERRIDE_CONSUMED"];
+export type PressureAdmissionRejectionCode = (typeof PRESSURE_ADMISSION_REJECTION_CODES)[number];
+/** One normalized sample from the bounded machine pressure ring. Ratios are
+ * 0..1 (load1 is load average over cores, so it can exceed 1). */
+export interface PressureAdmissionSample {
+    collectedAt: string;
+    /** Process-inventory generation the sample was collected under, when known. */
+    generation?: string;
+    sampleId?: number;
+    cpu: number;
+    memory: number;
+    disk: number;
+    load1?: number;
+    /** True when this sample crossed the policy's critical thresholds. */
+    critical: boolean;
+}
+/** Attributed cause behind the pressure, from Goal 1 process attribution.
+ * Unknown/manual ownership can explain pressure but is never a cleanup target. */
+export interface PressureAdmissionCause {
+    process: string;
+    processCount: number;
+    cpuPercent: number;
+    rssBytes: number;
+    classification: ProcessOwnershipClass;
+    confidence: ProcessAttributionConfidence;
+    slotId?: string;
+    runId?: string;
+    /** False for unknown/manual ownership — those rows must never be rendered as
+     * cleanup targets, only as explanation. */
+    cleanupEligible: boolean;
+}
+/** Evidence backing an admission decision. `generation` is the preview
+ * identity: execution rejects decisions bound to a generation that no longer
+ * matches the current ring. */
+export interface PressureAdmissionEvidence {
+    machine: string;
+    /** Opaque identity of the latest sample (generation/sampleId/collectedAt
+     * digest). Null when no sample exists — nothing to bind an override to. */
+    generation: string | null;
+    evaluatedAt: string;
+    /** Tail of the bounded ring the policy evaluated, oldest first. */
+    samples: PressureAdmissionSample[];
+    consecutiveCriticalSamples: number;
+    requiredConsecutiveCriticalSamples: number;
+    /** Milliseconds after which the newest sample counts as stale. */
+    staleAfterMs: number;
+    latestSampleAt: string | null;
+    /** Present when a validation-only fixture forced this machine's state.
+     * Real fleet evidence never carries this flag. */
+    validationFixture?: true;
+}
+/** Preview identity carried from an admitted preview into execution. FIND_SLOT
+ * validates it against fresh evidence BEFORE claiming a slot and, on success,
+ * consumes it by stamping `consumedAt` — so a long PREPARE cannot turn a
+ * green-to-green generation move into a failure at launch time. Execution
+ * still recomputes fresh evidence and rejects if pressure became unsafe; an
+ * UNconsumed ref reaching execution (a path that skipped FIND_SLOT
+ * validation) is rejected with PRESSURE_PREVIEW_STALE as defense in depth.
+ * `consumedAt` is gateway-stamped only; client-supplied values are stripped. */
+export interface PressureAdmissionReference {
+    machine: string;
+    pressureGeneration: string;
+    consumedAt?: string;
+}
+/** One-dispatch operator override request. Bound to an exact machine and the
+ * pressure generation the operator saw; execution recomputes and rejects the
+ * override when the generation moved. */
+export interface PressureDispatchOverride {
+    machine: string;
+    pressureGeneration: string;
+    reason: string;
+}
+/** Audit record stamped by the gateway when an override is accepted. */
+export interface PressureOverrideAudit extends PressureDispatchOverride {
+    /** Authenticated principal that requested the override ('system' for
+     * in-process maintenance callers, which cannot originate from an ingress). */
+    principalId: string;
+    requestedAt: string;
+    /** An override never outlives the single dispatch it was issued for. */
+    scope: 'single-dispatch';
+    /**
+     * Durable consumption record, persisted at the launch gate BEFORE the
+     * runner starts (intent before effect). Bound to one exact DISPATCH engine
+     * attempt: a same-attempt provider retry sees its own attempt key and stays
+     * idempotent; a replay or new attempt rejects with
+     * PRESSURE_OVERRIDE_CONSUMED and needs a fresh override.
+     */
+    consumed?: {
+        attemptKey: string;
+        consumedAt: string;
+    };
+}
+/**
+ * What the policy WOULD have rejected with, on a dispatch that was admitted
+ * anyway because the gate is switched off. Advisory only: nothing downstream
+ * may turn this into a refusal.
+ */
+export interface PressureAdmissionAdvisory {
+    code: PressureAdmissionRejectionCode;
+    /** Operator-facing reason. Backend-owned; clients render it verbatim. */
+    reason: string;
+    causes: PressureAdmissionCause[];
+}
+export interface PressureAdmissionAdmitted {
+    outcome: 'admitted';
+    machine: string;
+    state: Extract<PressureAdmissionState, 'green' | 'transient' | 'override' | 'disabled'>;
+    evidence: PressureAdmissionEvidence;
+    /** Present only when state='override': the accepted one-shot override. */
+    override?: PressureOverrideAudit;
+    /**
+     * Present ONLY on state='disabled': the gate is switched off, so this
+     * dispatch was admitted without enforcement. Distinguishes "evaluated and
+     * green" from "not enforced at all".
+     */
+    enforced?: false;
+    /** Present when an unenforced decision would otherwise have been rejected. */
+    advisory?: PressureAdmissionAdvisory;
+}
+export interface PressureAdmissionRejected {
+    outcome: 'rejected';
+    machine: string;
+    state: Extract<PressureAdmissionState, 'sustained-critical' | 'unavailable' | 'stale'>;
+    code: PressureAdmissionRejectionCode;
+    /** Operator-facing reason. Backend-owned; clients render it verbatim. */
+    reason: string;
+    causes: PressureAdmissionCause[];
+    evidence: PressureAdmissionEvidence;
+    /** True when a fresh explicit override against `evidence.generation` can
+     * admit one dispatch. False for unavailable/stale evidence — fail closed. */
+    overridable: boolean;
+}
+export type PressureAdmissionDecision = PressureAdmissionAdmitted | PressureAdmissionRejected;
+/** Gateway-owned durable switch for pressure-based dispatch prevention.
+ * Default DISABLED — sustained-pressure dispatch prevention is opt-in. Enabling
+ * turns on pressure rejection/override prompts; sampling, history, and charts
+ * run either way. Never affects slot ownership, capability, runner, branch, or
+ * other safety checks. */
+export interface PressureAdmissionControlState {
+    enabled: boolean;
+    /** ISO timestamp of the last change; null when still at the default. */
+    updatedAt: string | null;
+    /** Authenticated principal that made the last change; null at the default. */
+    updatedBy: string | null;
+    /**
+     * Set when FARMSLOT_DISPATCH_PRESSURE_ADMISSION is exported on the gateway
+     * process. The env value WINS over the durable state above, which is still
+     * reported verbatim so an operator can see both.
+     */
+    envOverride?: DispatchPressureAdmissionMode;
+}
+export interface PressureAdmissionSetEnabledParams {
+    enabled: boolean;
+}
+export type PressureAdmissionGetResult = PressureAdmissionControlState;
+export type PressureAdmissionSetEnabledResult = PressureAdmissionControlState;
+export declare function isPressureAdmissionRejected(decision: PressureAdmissionDecision | undefined): decision is PressureAdmissionRejected;
+//# sourceMappingURL=pressure-admission.d.ts.map

package/dist/contracts/pressure-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pressure-admission.d.ts","sourceRoot":"","sources":["../../src/contracts/pressure-admission.ts"],"names":[],"mappings":"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"}

package/dist/contracts/pressure-admission.js

@@ -0,0 +1,26 @@
+// Sustained-pressure dispatch admission contract (MANUAL-000109).
+//
+// One backend-owned decision shared by dispatch preview, automatic slot
+// selection, and dispatch execution. Clients render these decisions and never
+// re-derive thresholds. The evidence is the Goal 1 node-pressure history and
+// process attribution — no dispatch-side sampler exists.
+export const DISPATCH_PRESSURE_ADMISSION_MODES = [
+    'off',
+    'refuse',
+];
+/** Stable machine-readable rejection codes. Never rename — clients and
+ * operators key automation off these. */
+export const PRESSURE_ADMISSION_REJECTION_CODES = [
+    'PRESSURE_SUSTAINED_CRITICAL',
+    'PRESSURE_EVIDENCE_UNAVAILABLE',
+    'PRESSURE_EVIDENCE_STALE',
+    'PRESSURE_PREVIEW_STALE',
+    'PRESSURE_OVERRIDE_STALE',
+    'PRESSURE_OVERRIDE_MISMATCH',
+    'PRESSURE_OVERRIDE_REASON_REQUIRED',
+    'PRESSURE_OVERRIDE_CONSUMED',
+];
+export function isPressureAdmissionRejected(decision) {
+    return decision?.outcome === 'rejected';
+}
+//# sourceMappingURL=pressure-admission.js.map

package/dist/contracts/pressure-admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pressure-admission.js","sourceRoot":"","sources":["../../src/contracts/pressure-admission.ts"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,EAAE;AACF,wEAAwE;AACxE,8EAA8E;AAC9E,6EAA6E;AAC7E,yDAAyD;AAazD,MAAM,CAAC,MAAM,iCAAiC,GAA6C;IACzF,KAAK;IACL,QAAQ;CACT,CAAC;AAgBF;yCACyC;AACzC,MAAM,CAAC,MAAM,kCAAkC,GAAG;IAChD,6BAA6B;IAC7B,+BAA+B;IAC/B,yBAAyB;IACzB,wBAAwB;IACxB,yBAAyB;IACzB,4BAA4B;IAC5B,mCAAmC;IACnC,4BAA4B;CACpB,CAAC;AA2KX,MAAM,UAAU,2BAA2B,CACzC,QAA+C;IAE/C,OAAO,QAAQ,EAAE,OAAO,KAAK,UAAU,CAAC;AAC1C,CAAC"}

package/dist/contracts/readiness.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Readiness record: what a harness did to make a checkout ready for a task and
+ * whether it succeeded. Farmslot defines the shape; a harness (mm-harness) fills
+ * the steps. Lives at `<artifacts dir>/sandbox.json` — the task's `artifacts/`
+ * for a skill run, the checkout runtime dir for a farm slot.
+ */
+export declare const READINESS_RECORD = "sandbox.json";
+export type ReadinessStepStatus = 'pass' | 'fail' | 'skipped';
+export interface ReadinessStep {
+    /** Stable step id, e.g. `doctor`, `status`, `launch`, `fixtures`, `verify`. */
+    id: string;
+    /** The exact command line the harness ran. */
+    command: string;
+    status: ReadinessStepStatus;
+    exitCode: number;
+    /** Report the step produced, relative to the record's directory, when it wrote one. */
+    reportPath?: string;
+    /** One-line reason for a fail or skip. */
+    reason?: string;
+}
+export interface ReadinessRecord {
+    schemaVersion: 1;
+    harness: {
+        name: string;
+        version: string;
+        /** How the executable was chosen: env override, task-local lock, PATH, … */
+        source: string;
+        executable: string;
+    };
+    platform: string;
+    mobilePlatform?: 'ios' | 'android';
+    steps: ReadinessStep[];
+    /** True when every non-skipped step passed. */
+    ready: boolean;
+    recordedAt: string;
+}
+//# sourceMappingURL=readiness.d.ts.map

package/dist/contracts/readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.d.ts","sourceRoot":"","sources":["../../src/contracts/readiness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAE/C,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,aAAa;IAC5B,+EAA+E;IAC/E,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,CAAC,CAAC;IACjB,OAAO,EAAE;QACP,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,4EAA4E;QAC5E,MAAM,EAAE,MAAM,CAAC;QACf,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IACnC,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,+CAA+C;IAC/C,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/contracts/readiness.js

@@ -0,0 +1,8 @@
+/**
+ * Readiness record: what a harness did to make a checkout ready for a task and
+ * whether it succeeded. Farmslot defines the shape; a harness (mm-harness) fills
+ * the steps. Lives at `<artifacts dir>/sandbox.json` — the task's `artifacts/`
+ * for a skill run, the checkout runtime dir for a farm slot.
+ */
+export const READINESS_RECORD = 'sandbox.json';
+//# sourceMappingURL=readiness.js.map

package/dist/contracts/readiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness.js","sourceRoot":"","sources":["../../src/contracts/readiness.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAc,CAAC"}

package/dist/contracts/resource-posture.d.ts

@@ -0,0 +1,379 @@
+/**
+ * Run resource posture (ADR-054).
+ *
+ * The Gateway owns one semantic posture per run describing which runtime
+ * capabilities should be live at the current lifecycle boundary. Clients render
+ * the Gateway's decision — desired disposition, observed provider state, the
+ * winning policy source — and never resolve policy themselves.
+ */
+import type { DeviceInventoryKey } from './device-inventory.js';
+import type { MachinePauseEligibilityDetails } from './runs.js';
+import type { RuntimeCapabilityAcquireConflict, RuntimeCapabilityClaimScope, RuntimeCapabilityHealthState, RuntimeCapabilityLeaseOwner, RuntimeCapabilityLeaseState, RuntimeCapabilityTarget } from './runtime-capabilities.js';
+/**
+ * The lease fields `observedStateForLease` reads. Structural so this module
+ * stays free of a value-level dependency on the lease type.
+ */
+export interface RuntimeCapabilityLeaseLike {
+    state: RuntimeCapabilityLeaseState;
+    health: {
+        state: RuntimeCapabilityHealthState;
+    };
+    keepWarmUntil?: string;
+    cleanupFailure?: string;
+}
+/** Semantic lifecycle intent. Never derived from run status, step names, or slot phases. */
+export declare const RESOURCE_POSTURES: readonly ["active", "operator-wait", "parked", "terminal"];
+export type ResourcePosture = (typeof RESOURCE_POSTURES)[number];
+/** Operator vocabulary at a human gate; each resolves to a posture plus proof plan. */
+export declare const RESOURCE_POSTURE_GATE_CHOICES: readonly ["keep-for-validation", "minimize", "free-slot", "project-default"];
+export type ResourcePostureGateChoice = (typeof RESOURCE_POSTURE_GATE_CHOICES)[number];
+/**
+ * Dispatch-time preset for every durable wait of a run. `project-default` is
+ * excluded: a preset that defers to the lower precedence levels is a no-op, and
+ * omitting the field already expresses it.
+ */
+export declare const RESOURCE_POSTURE_WAIT_POLICIES: readonly ["keep-for-validation", "minimize", "free-slot"];
+export type ResourcePostureWaitPolicy = (typeof RESOURCE_POSTURE_WAIT_POLICIES)[number];
+/** Which precedence level produced the effective policy. */
+export declare const RESOURCE_POSTURE_POLICY_SOURCES: readonly ["gate-choice", "run-dispatch", "project-default", "framework-default"];
+export type ResourcePosturePolicySource = (typeof RESOURCE_POSTURE_POLICY_SOURCES)[number];
+/** What the Gateway intends for a capability. Distinct from what is observed. */
+export declare const RESOURCE_POSTURE_DISPOSITIONS: readonly ["acquired", "warm", "stopped"];
+export type ResourcePostureDesiredDisposition = (typeof RESOURCE_POSTURE_DISPOSITIONS)[number];
+/**
+ * What the provider is actually doing. A released lease with a live keep-warm
+ * provider is `running`, not `stopped`.
+ */
+export declare const RESOURCE_POSTURE_OBSERVED_STATES: readonly ["running", "stopped", "unhealthy", "transitioning", "unknown"];
+export type ResourcePostureObservedState = (typeof RESOURCE_POSTURE_OBSERVED_STATES)[number];
+/** Per-provider project retention policy for a posture. */
+export declare const RESOURCE_POSTURE_RETENTIONS: readonly ["retain", "warm", "stop"];
+export type ResourcePostureRetention = (typeof RESOURCE_POSTURE_RETENTIONS)[number];
+/**
+ * Postures a project may configure retention for. `active` is derived from the
+ * current proof plan and `parked` delegates to machine parking, so neither
+ * accepts a retention override.
+ */
+export declare const RESOURCE_POSTURE_RETENTION_BOUNDARIES: readonly ["operator-wait", "terminal"];
+export type ResourcePostureRetentionBoundary = (typeof RESOURCE_POSTURE_RETENTION_BOUNDARIES)[number];
+/** Project-level posture defaults; per-provider `retention` overrides these. */
+export interface ProjectResourcePostureConfig {
+    defaults?: Partial<Record<ResourcePostureRetentionBoundary, ResourcePostureRetention>>;
+}
+export interface ResourcePostureCapabilityState {
+    capabilityId: string;
+    desiredDisposition: ResourcePostureDesiredDisposition;
+    observedState: ResourcePostureObservedState;
+    policySource: ResourcePosturePolicySource;
+    reason: string;
+    leaseId?: string;
+    owner?: RuntimeCapabilityLeaseOwner;
+    /**
+     * The device identity the holding lease actually resolved to, when the
+     * provider takes one. Read off the lease's stored acquire parameters, so a
+     * client shows the device that is really in use rather than the slot's
+     * configured default after a re-target.
+     */
+    target?: RuntimeCapabilityTarget;
+    /** Deadline until which a released provider stays live. */
+    warmUntil?: string;
+    lastTransitionAt?: string;
+    releaseEffects: string[];
+    cleanupFailure?: string;
+}
+export type ResourcePostureRejection = {
+    kind: 'park-ineligible';
+    /** Machine-parking eligibility code, passed through unchanged. */
+    code: string;
+    reason: string;
+    /** Structured facts for the code, passed through unchanged. */
+    details?: MachinePauseEligibilityDetails;
+} | {
+    kind: 'capability-unavailable';
+    capabilityId: string;
+    reason: string;
+    conflict: RuntimeCapabilityAcquireConflict;
+} | {
+    /**
+     * A re-target named a device the slot's machine does not have
+     * (MANUAL-000124). Refused BEFORE the run's current device is released,
+     * so a typo costs the run nothing.
+     */
+    kind: 'device-unknown';
+    capabilityId: string;
+    /** The machine whose inventory was read. Device names are machine-scoped. */
+    machine: string;
+    /** The device-identity key the target named. */
+    key: DeviceInventoryKey;
+    identity: string;
+    /** Identities of the same key the machine does have, nearest first. */
+    nearest: string[];
+    reason: string;
+} | {
+    kind: 'invalid-request';
+    reason: string;
+};
+export declare const RESOURCE_POSTURE_TRANSITION_OUTCOMES: readonly ["in-progress", "applied", "idempotent", "partial", "rejected", "failed"];
+export type ResourcePostureTransitionOutcome = (typeof RESOURCE_POSTURE_TRANSITION_OUTCOMES)[number];
+export interface ResourcePostureTransitionFailure {
+    capabilityId: string;
+    leaseId?: string;
+    reason: string;
+}
+export interface ResourcePostureTransition {
+    /** Caller-supplied `operationId` when present, so a replay returns this record. */
+    id: string;
+    posture: ResourcePosture;
+    policySource: ResourcePosturePolicySource;
+    gateChoice?: ResourcePostureGateChoice;
+    requestedAt: string;
+    completedAt?: string;
+    outcome: ResourcePostureTransitionOutcome;
+    effects: string[];
+    progress: {
+        total: number;
+        completed: number;
+    };
+    failures: ResourcePostureTransitionFailure[];
+    rejection?: ResourcePostureRejection;
+}
+/** Exact effect of applying a posture, returned before an operator commits. */
+export interface ResourcePosturePlan {
+    runId: string;
+    slotId: string | null;
+    posture: ResourcePosture;
+    policySource: ResourcePosturePolicySource;
+    reason: string;
+    acquire: ResourcePostureCapabilityState[];
+    retain: ResourcePostureCapabilityState[];
+    warm: ResourcePostureCapabilityState[];
+    stop: ResourcePostureCapabilityState[];
+    /** Declared release effects of everything this plan would stop. */
+    effects: string[];
+    rejection?: ResourcePostureRejection;
+}
+/** Persisted on the run so a reconnecting client sees the same thing. */
+export interface RunResourcePostureState {
+    posture: ResourcePosture;
+    policySource: ResourcePosturePolicySource;
+    gateChoice?: ResourcePostureGateChoice;
+    /**
+     * The run generation a `machine.pause.restore` replay took ownership at, when
+     * that restore re-presented a gate whose stored choice would re-park the run.
+     *
+     * Without it a run whose stored choice is `free-slot` re-parks itself the
+     * instant restore re-presents its gate: the replayed gate reaches the
+     * operator-wait boundary, the stored choice is carried forward, and the run
+     * parks again before the operator ever sees it. The restored gate therefore
+     * falls back to the framework default once; choosing `free-slot` again is
+     * still available, it just has to be chosen rather than inherited.
+     *
+     * Keyed on the GENERATION rather than a bare flag so it cannot outlive the
+     * gate it was set for. The replay is fire-and-forget: if it never reaches a
+     * wait boundary, a bare flag would sit on the run and silently swallow the
+     * operator's choice at some unrelated later wait. A generation that has moved
+     * on makes the suppression simply not apply.
+     *
+     * Cleared by the first wait boundary after it is set, whether or not that
+     * boundary carried an explicit choice — an operator who answers the restored
+     * gate consumes it just as an inheriting wait does.
+     */
+    gateChoiceSuppressedForGeneration?: number;
+    waitPolicy?: ResourcePostureWaitPolicy;
+    capabilities: ResourcePostureCapabilityState[];
+    /**
+     * The scoped resource claim this run is queued behind, while it is queued.
+     *
+     * Derived from the last transition's rejection rather than written
+     * separately, so it cannot outlive the wait it describes. A later transition
+     * that is not a scoped wait clears it. The work-graph reads this to report
+     * the node as `waitingOn.kind: 'resource'`.
+     */
+    resourceWait?: RunResourceWait;
+    /** ADR-038: no posture resolved here stops a gate-held worker. */
+    workerRetained: boolean;
+    lastTransition?: ResourcePostureTransition;
+    /**
+     * Recent transitions, newest first, bounded by
+     * `RESOURCE_POSTURE_TRANSITION_HISTORY`. Replaying an `operationId` returns the
+     * stored outcome for any id still in here, so a retry of an earlier operation
+     * cannot re-execute and undo a later one.
+     */
+    recentTransitions?: ResourcePostureTransition[];
+    updatedAt: string;
+}
+/**
+ * How far along a run's place in a scoped claim's queue is.
+ *
+ * `queued` is waiting its turn behind a holder. `granted` is the reservation
+ * the drain hands the head waiter: the claim is now held for this run and no
+ * provider has booted for it yet, so the run is not waiting on anyone else —
+ * it is waiting on its own completion. The two are reported separately because
+ * a `granted` wait that never clears is a stranded claim nobody else can take,
+ * and reporting nothing at all is how that used to stay invisible.
+ */
+export declare const RUN_RESOURCE_WAIT_PHASES: readonly ["queued", "granted"];
+export type RunResourceWaitPhase = (typeof RUN_RESOURCE_WAIT_PHASES)[number];
+/**
+ * A run's durable place in a scoped claim's queue.
+ *
+ * `position` is a snapshot from the moment the acquire was refused, not a live
+ * counter: nothing renumbers a queue, and re-deriving it here would need the
+ * whole fleet's leases on every read of a run. A `granted` wait is past the
+ * queue entirely and reports position 0.
+ */
+export interface RunResourceWait {
+    capabilityId: string;
+    claimId: string;
+    scope: RuntimeCapabilityClaimScope;
+    phase: RunResourceWaitPhase;
+    /** The run holding the claim, which is usually on another slot. */
+    blockingOwner: RuntimeCapabilityLeaseOwner;
+    /** The queued lease that holds this run's place in line. */
+    queuedLeaseId: string;
+    /** 1-based place in line, or 0 once the claim is reserved for this run. */
+    position: number;
+    since: string;
+    reason: string;
+}
+/** How many transitions a run keeps for operation-id replay. */
+export declare const RESOURCE_POSTURE_TRANSITION_HISTORY = 20;
+/** Gate choice -> posture. The only place this mapping exists. */
+export declare function postureForGateChoice(choice: Exclude<ResourcePostureGateChoice, 'project-default'>): ResourcePosture;
+/**
+ * The single derivation of a provider's observed state from its lease.
+ *
+ * Shared so the Gateway and every client answer "is this provider running?"
+ * identically. A client that re-derives this locally will drift — Slot View
+ * once decided an elapsed warm deadline meant `stopped` while the Gateway
+ * reported `unknown`, which labels a live provider as dead.
+ *
+ * `nowMs` is passed in so the caller evaluates the warm deadline against the
+ * same instant it rendered with.
+ */
+export declare function observedStateForLease(lease: RuntimeCapabilityLeaseLike | undefined, nowMs: number): ResourcePostureObservedState;
+export declare function isResourcePosture(value: unknown): value is ResourcePosture;
+export declare function isResourcePostureGateChoice(value: unknown): value is ResourcePostureGateChoice;
+export declare function isResourcePostureWaitPolicy(value: unknown): value is ResourcePostureWaitPolicy;
+/**
+ * How the observed provider state stands against what the Gateway wanted.
+ *
+ * `unproven` is deliberately not folded into `mismatch` or `matches`: an
+ * `unknown` observation means the Gateway could not see the provider, and
+ * claiming either outcome from it would be a guess.
+ */
+export type ResourcePostureRowStatus = 'matches' | 'pending' | 'mismatch' | 'unproven';
+/**
+ * The single comparison of desired disposition against observed provider state.
+ *
+ * Shared so Command Center, Companion, and the CLI agree on when the Gateway
+ * got what it asked for. A client that re-derives this locally drifts, and the
+ * drift is always in the same direction: reporting a provider as handled when
+ * nothing observed it.
+ */
+export declare function resourcePostureRowStatus(desired: ResourcePostureDesiredDisposition, observed: ResourcePostureObservedState): ResourcePostureRowStatus;
+/**
+ * Counts of what the providers are observed to be doing, not of what was
+ * wanted. `stopped` requires an observed `stopped`: a provider the Gateway
+ * intended to stop but which is still running, or whose cleanup failed, must
+ * never be counted as stopped. Anything the Gateway cannot currently place —
+ * unknown, transitioning, or contradicting its intent — lands in `unresolved`
+ * so the buckets always account for every capability instead of quietly
+ * dropping one.
+ */
+export interface ResourcePostureCounts {
+    retained: number;
+    warm: number;
+    stopped: number;
+    failed: number;
+    unresolved: number;
+}
+export declare function resourcePostureCounts(capabilities: readonly ResourcePostureCapabilityState[], lastTransition?: ResourcePostureTransition): ResourcePostureCounts;
+/**
+ * Transition failures that are not already reported on a capability entry.
+ *
+ * A failed cleanup lands in both places: the transition's failure list and the
+ * capability's own `cleanupFailure`. Reporting both gives the operator the same
+ * alert twice. The capability entry wins — it sits next to that capability's
+ * desired and observed state, which is the context needed to act on it.
+ *
+ * The match is on capability AND reason. The Gateway reports a failure per
+ * lease while a capability entry carries one reason, so suppressing every
+ * failure for a capability that had any entry failure would silently drop a
+ * sibling lease's different failure — the one case where the transition list is
+ * the only place that failure is reported at all.
+ */
+export declare function resourcePostureTransitionFailuresToShow(capabilities: readonly Pick<ResourcePostureCapabilityState, 'capabilityId' | 'cleanupFailure'>[], lastTransition?: ResourcePostureTransition): ResourcePostureTransitionFailure[];
+/**
+ * Outcomes that end a transition. `in-progress` is deliberately absent: it is a
+ * wait, not an answer, and adopting it reports a reconciliation that can still
+ * fail as the operator's result.
+ *
+ * This is an allowlist rather than `!== 'in-progress'` so a new outcome added to
+ * the protocol is treated as non-terminal until it is considered here. The
+ * inverse defaults a new outcome to terminal on whichever client happens to
+ * update last, which is the wrong direction to fail in.
+ */
+export declare const RESOURCE_POSTURE_TERMINAL_OUTCOMES: readonly ResourcePostureTransitionOutcome[];
+export declare function isTerminalResourcePostureOutcome(outcome: ResourcePostureTransitionOutcome): boolean;
+/** How many status reads a client waits through before reporting reconciliation pending. */
+export declare const RESOURCE_POSTURE_TRANSITION_POLL_LIMIT = 10;
+/**
+ * What a client knew before it sent a resolution, so the answer can be told
+ * apart from what was already there.
+ */
+export interface ResourcePostureTransitionBaseline {
+    /** Transition ids the Gateway had already recorded. */
+    transitionIds: readonly string[];
+    /**
+     * Newest `requestedAt` among those, in the Gateway's own clock. Recency is
+     * compared Gateway-to-Gateway; a client clock never enters the comparison.
+     */
+    newestRequestedAt: string | undefined;
+    /** The gate choice the client forwarded, when it forwarded one. */
+    choice: ResourcePostureGateChoice | null;
+}
+/** The records to correlate over, newest first, as the protocol persists them. */
+export declare function resourcePostureTransitions(state: Pick<RunResourcePostureState, 'recentTransitions' | 'lastTransition'> | undefined): readonly ResourcePostureTransition[];
+export declare function resourcePostureTransitionBaseline(state: Pick<RunResourcePostureState, 'recentTransitions' | 'lastTransition'> | undefined, choice: ResourcePostureGateChoice | null): ResourcePostureTransitionBaseline;
+/**
+ * The transition a resolution actually produced, or `undefined` while the
+ * Gateway has not recorded one yet.
+ *
+ * `run.resolveDecision` returns before posture reconciliation finishes, so the
+ * record on its response is frequently the one from BEFORE the resolution.
+ * Presenting that reports an old outcome as the answer to what the operator just
+ * did. Every client applies these four rules, from this one implementation:
+ *
+ * 1. Novelty. A record whose id was already in the baseline is one the Gateway
+ *    had before the resolution, and is never adopted.
+ * 2. Recency, in Gateway time. A record must not be older than the newest
+ *    `requestedAt` in the baseline. Both sides come from the Gateway, so no
+ *    client clock is involved: anchoring on the client's send moment compares a
+ *    phone or browser clock against the Gateway's, and a skewed client either
+ *    adopts a stale record or rejects the real one forever. Not-older rather
+ *    than strictly-newer, so two reconciliations in the same millisecond are not
+ *    dropped; novelty already excludes the baseline itself. This rule excludes a
+ *    backfilled or out-of-order record; it cannot exclude a genuinely concurrent
+ *    one, which is what rule 3 is for.
+ * 3. Attribution. A record attributed to a different gate choice is excluded. A
+ *    record carrying no `gateChoice` is never excluded on that basis, because
+ *    the Gateway drops `project-default` before it picks a policy source and
+ *    genuine rejections can also arrive without one. Among the survivors, a
+ *    record the Gateway attributed to this choice WINS over an unattributed one;
+ *    an unattributed record is only the fallback. Without that preference a
+ *    concurrent unattributed reconciliation that lands afterwards is newest and
+ *    therefore chosen, which misattributes it.
+ * 4. Terminality is the caller's half: `in-progress` is not an answer, so the
+ *    caller keeps polling until `isTerminalResourcePostureOutcome`, bounded by
+ *    `RESOURCE_POSTURE_TRANSITION_POLL_LIMIT`, and reports the wait on timeout.
+ *
+ * What this still cannot do: the record carries no decision key, and the
+ * resolve path supplies no `operationId` for the Gateway to mint the id from, so
+ * for a record with nothing attributed the correlation is positional. A
+ * concurrent reconciliation from another boundary could in principle be picked
+ * up. Surfaced wording must therefore describe what the run's posture did, never
+ * claim the operator's choice caused it.
+ */
+export declare function correlateResourcePostureTransition(baseline: ResourcePostureTransitionBaseline, records: readonly ResourcePostureTransition[]): ResourcePostureTransition | undefined;
+//# sourceMappingURL=resource-posture.d.ts.map