@farmslot/protocol 0.21.0 → 0.25.0

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/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

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

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