@farmslot/protocol 0.21.0 → 0.26.0

package/dist/contracts/gate-park.d.ts

@@ -0,0 +1,284 @@
+/**
+ * Gate-park state for clients (ADR-054 `free-slot` at an operator wait).
+ *
+ * A run parked with `free-slot` keeps its gate answerable while its slot goes
+ * back to dispatch. Three facts then live in three different places — the park
+ * record's slot disposition, the restore stages the record owes, and the
+ * Gateway's verdict on whether the original slot can take the run back — and a
+ * surface that reads any one of them alone gets the run's state wrong:
+ *
+ *   - occupancy alone reports a restore that re-bound the slot and then failed
+ *     as "back", so the gate looks answerable against a worker nothing proved;
+ *   - the phase alone reports a `partial` that never reached the slot the same
+ *     way as one that freed it;
+ *   - a client that decides slot availability itself picks a slot the Gateway
+ *     did not, which is the one thing ADR-054 forbids.
+ *
+ * So this module owns the single reading, and Command Center, Companion, and
+ * the CLI all render it. Availability is never derived here: it is carried in
+ * from a Gateway verdict, or reported as not known.
+ *
+ * The predicates below moved out of the Gateway so clients share the exact
+ * definitions the Gateway acts on rather than approximations of them.
+ */
+import { type MachineParkPhase, type MachineParkRestoreRefusal, type MachineParkRestoreStage, type MachineParkSlotDisposition, type MachineParkWorkspace, type Run } from './runs.js';
+/**
+ * Whether this run's machine-park record released its slot (ADR-054
+ * `free-slot` at an operator wait, amending ADR-038's gate-held slot hold).
+ *
+ * `slotFreedAt` records the fact, not the intent: it is written only after the
+ * park stopped the runner and every manifest resource AND the ownership
+ * release landed, so a partial park never reads as freed. While it is set, the
+ * park record — not the slot row — is the authority for the run's slot
+ * binding: the run keeps `slotId` (the recovery handle and the workspace
+ * branch key off it) but stops counting as an occupant of that slot.
+ *
+ * This is the OCCUPANCY predicate. It must never claim a slot is free before
+ * the release actually landed, so dispatch cannot hand out a slot whose worker
+ * is still running. Use `isGateParkInFlightOrFreed` for the safety fences,
+ * which have the opposite bias.
+ */
+export declare function isSlotFreedByPark(run: Pick<Run, 'park'>): boolean;
+/**
+ * Whether a gate park still owes a restore before its gate may be answered.
+ *
+ * The question consumption asks, and it is NOT "does the run occupy its slot".
+ * A restore that re-bound the slot, booted its resources, and then failed to
+ * get a structured acknowledgement out of the worker leaves an occupied slot
+ * and a running process — and answering the gate there drives the engine
+ * against a worker that never confirmed it came back. So this keys on the
+ * restore's own stage record, which is the only thing that says what landed.
+ */
+export declare function needsGateParkRestore(run: Pick<Run, 'park'>): boolean;
+/**
+ * Whether a slot-freeing park is either done or still in flight for this run.
+ *
+ * The opposite bias to `isSlotFreedByPark`: it goes true the moment the
+ * write-ahead record declares a freeing park and stays true through the window
+ * where the runner and resources are being stopped but `slotFreedAt` has not
+ * been written yet.
+ *
+ * Every guard that must not act on a run whose slot is disappearing uses this:
+ * resolving a gate, applying a posture, driving a resolved gate onward, or
+ * tearing the slot down after a failure. Answering a gate mid-park would
+ * publish against a worker that is being stopped underneath it.
+ *
+ * It is keyed on intent-or-fact HONESTLY, which matters as much as the fence
+ * itself. A fence that never lifts is not a fence, it is a strand: the run can
+ * neither answer its gate nor be restored, and cancelling it is the only exit.
+ * So:
+ *
+ *   - the record owes a restore — it freed the slot, or a restore re-bound it
+ *     and has not settled `restored`. Fenced, until that restore or a cancel.
+ *   - a park that never reached the slot and settled `partial` — it will not
+ *     finish. It is still fenced
+ *     while ANY of its effects is outstanding: a detach not yet rolled back, or
+ *     a runner that is not PROVABLY still running. A stopped worker cannot act
+ *     on a gate answer, and letting the operator answer anyway would be the
+ *     silent version of the strand. `machine.pause.restore` is the exit: it
+ *     reloads the worker and settles the record, which lifts the fence. Only a
+ *     park that detached nothing and left an observably live worker leaves the
+ *     run answerable where it stands.
+ *   - otherwise, while the intent is live — fenced.
+ */
+export declare function isGateParkInFlightOrFreed(run: Pick<Run, 'park'>): boolean;
+/**
+ * Whether machine parking still holds this run.
+ *
+ * The park RECORD is the authority for "is this run parked", not the run's
+ * persisted posture. A restore or a cancel settles the record while the posture
+ * it was applied under stays on the run, so a reader that trusts the posture
+ * decides an already-restored run is still parked — and then refuses to park it
+ * again, forever, as a no-op.
+ */
+export declare function hasLiveParkRecord(run: Pick<Run, 'park'>): boolean;
+/**
+ * Where the run's slot stands under its park record.
+ *
+ * `freeing` and `freed` are deliberately different words: the first is a park
+ * whose release has not landed, and calling it freed would advertise a slot
+ * whose worker is still being stopped. `restoring` is likewise not `freed`:
+ * the slot is back under the run, but the restore still owes stages.
+ *
+ * The two `partial` states are split for the same reason, and it is the split
+ * that matters most to an operator. A `partial` park has SETTLED — it will not
+ * finish — so calling it "still landing" promises a completion that is never
+ * coming, and telling the operator to wait is advice that cannot work. Which of
+ * the two it is comes from the Gateway's own fence, never from a second reading
+ * of the record: a partial that detached nothing and left an observably live
+ * worker is answerable where it stands, and every other partial owes an
+ * explicit restore before its gate may be answered.
+ */
+export type GateParkSlotState = 
+/** A park that holds the run's slot — the machine-wide pause of ADR-053. */
+'retained'
+/** A freeing park still in flight; its slot release has not landed yet. */
+ | 'freeing'
+/**
+ * A freeing park that failed before it reached the slot and left nothing
+ * outstanding. The worker is observably running and the gate is answerable.
+ */
+ | 'partial-answerable'
+/**
+ * A freeing park that failed with an effect outstanding — a detach not rolled
+ * back, or a worker that is not provably alive. Only a restore clears it.
+ */
+ | 'partial-needs-restore'
+/** The slot is released; dispatch may select it while the run stays parked. */
+ | 'freed'
+/** A restore re-bound the slot but still owes stages before the gate is answerable. */
+ | 'restoring'
+/**
+ * A restore re-bound a DIFFERENT slot than the park freed, because a
+ * successor took the original, and still owes stages. Split from `restoring`
+ * because the operator's attach target moved: telling them the run is coming
+ * back into the slot they parked it from would send them to a pane that
+ * belongs to someone else.
+ */
+ | 'rehoming'
+/** The record is `restored` or `cancelled`; nothing is outstanding. */
+ | 'settled';
+/** How far the current freed-slot restore attempt got. */
+export interface GateParkRestoreStageView {
+    state: 'not-started' | 'in-progress' | 'complete';
+    /** The stage being attempted right now, written before it runs. */
+    attempting: MachineParkRestoreStage | null;
+    completed: readonly MachineParkRestoreStage[];
+    /** Stages still owed, in the order the restore owes them. */
+    remaining: readonly MachineParkRestoreStage[];
+}
+/**
+ * The slot a restore would put the run back into.
+ *
+ * `available` is `null` when nothing has told this client whether that slot can
+ * take the run back. Only the Gateway answers that question — through
+ * `machine.pause.restore` — so a surface without one reports "not known" rather
+ * than guessing from the record.
+ *
+ * `slotId` is the target the Gateway picked and may differ from
+ * `originalSlotId`: when a successor took the slot the park freed, the Gateway
+ * re-homes the run to another free slot on the same machine. A client renders
+ * what it is given and never picks a slot itself.
+ */
+export interface GateParkRestoreTargetView {
+    slotId: string;
+    /** The slot the park record names. Equal to `slotId` unless the restore re-homes. */
+    originalSlotId: string;
+    disposition: MachineParkSlotDisposition;
+    available: boolean | null;
+    /** The Gateway's verdict code for that availability, when one was supplied. */
+    code?: string;
+    reason?: string;
+}
+/** How a restore proved the worker came back. */
+export interface GateParkWorkerProofView {
+    /** `structured` delivered a turn the runner acknowledged; `adopted` inherited a live session. */
+    kind: 'structured' | 'adopted';
+    reason: string;
+    acceptedAt: string;
+}
+/** One reading of a run's gate park, shared by every client surface. */
+export interface GateParkView {
+    runId: string;
+    machine: string;
+    /** The park record's slot — the run's slot binding while the record is live. */
+    slotId: string;
+    phase: MachineParkPhase;
+    slotState: GateParkSlotState;
+    /** Absent on records written before slot freeing existed; read as `retained`. */
+    slotDisposition: MachineParkSlotDisposition;
+    /** The slot dispatch may hand to another run right now, or `null`. */
+    freedSlotId: string | null;
+    slotFreedAt?: string;
+    slotReboundAt?: string;
+    /** The branch and tip a freeing park took out of the slot's working tree. */
+    preservedWorkspace?: MachineParkWorkspace;
+    /**
+     * Whether answering this run's gate must restore the run first. The same
+     * question `run.resolveDecision` asks before it consumes the decision.
+     */
+    restoreBeforeGateAnswer: boolean;
+    restoreStage: GateParkRestoreStageView;
+    restoreTarget: GateParkRestoreTargetView;
+    /** Why the last restore attempt refused, when it refused without changing anything. */
+    refusal?: MachineParkRestoreRefusal;
+    /** How the last restore proved the worker back, once one did. */
+    workerProof?: GateParkWorkerProofView;
+}
+/**
+ * A Gateway-resolved restore target. Structural so this module keeps no
+ * value-level dependency on the RPC layer, which imports these contracts.
+ * `MachinePauseRestoreTarget` and `MachinePauseEligibility` satisfy it.
+ */
+export interface GateParkRestoreVerdict {
+    target: {
+        slotId: string;
+        originalSlotId?: string;
+        disposition: MachineParkSlotDisposition;
+        available: boolean;
+    };
+    eligibility?: {
+        code: string;
+        reason: string;
+    };
+}
+/**
+ * The one reading of a run's gate park, or `null` when the run has no park
+ * record at all.
+ *
+ * `verdict` carries a Gateway-resolved restore target when the caller has read
+ * one (`machine.pause.restore`). Without it the target's `available` stays
+ * `null`: the record says which slot a restore would use, never whether that
+ * slot is free right now.
+ */
+export declare function gateParkView(run: Pick<Run, 'id' | 'park'>, verdict?: GateParkRestoreVerdict): GateParkView | null;
+/**
+ * The gate park a client should render beside a run's gate, or `null` when
+ * there is nothing outstanding to say.
+ *
+ * A settled record is deliberately excluded: it describes a park the operator
+ * already resolved, and showing it beside a live gate reads as "this run is
+ * parked" when it is not.
+ */
+export declare function liveGateParkView(run: Pick<Run, 'id' | 'park'>, verdict?: GateParkRestoreVerdict): GateParkView | null;
+/**
+ * Operator wording for the run's slot under its park.
+ *
+ * The sentences live here rather than in each client because the same claim has
+ * to read the same way in Command Center, Companion, and the CLI. A per-client
+ * copy is how "parked" came to mean the slot was gone on one surface and still
+ * held on another.
+ */
+export declare function gateParkStateLabel(view: GateParkView): string;
+/** One compact line: what the park did with the slot, the branch it preserved, what it still owes. */
+export declare function gateParkSummaryLine(view: GateParkView): string;
+/**
+ * What the operator must know before answering this run's gate, or `null` when
+ * the park has nothing to say about it.
+ *
+ * A refused restore is reported as a block on the answer, never as a failed
+ * run: the record stays parked, the decision stays pending, and the operator
+ * can answer again once the refusal clears — or cancel.
+ *
+ * `blocking` is carried rather than left to each client to infer from `kind`.
+ * A client that re-derives it gets the one case that matters backwards: a
+ * `partial` park that stopped short of the slot is a warning worth showing and
+ * is NOT a block, so styling every non-`restore-first` notice as a block puts
+ * a stop sign on a gate the Gateway will accept.
+ */
+export interface GateParkGateNotice {
+    kind: 'restore-first' | 'restore-blocked' | 'park-in-flight' | 'park-needs-restore' | 'park-answerable';
+    /** Whether this notice stands between the operator and answering the gate. */
+    blocking: boolean;
+    message: string;
+    /** The typed refusal the last restore attempt recorded. */
+    refusal?: MachineParkRestoreRefusal;
+    /**
+     * A Gateway verdict says the target IS available now, so the refusal above
+     * describes a previous attempt rather than the current answer. Without this
+     * a refusal that has since been overtaken keeps reading as a standing block.
+     */
+    refusalSuperseded?: boolean;
+}
+export declare function gateParkGateNotice(view: GateParkView | null): GateParkGateNotice | null;
+//# sourceMappingURL=gate-park.d.ts.map

package/dist/contracts/gate-park.d.ts.map

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