looply-cli 0.0.0-stage → 0.2.0

package/dist/autonomy-tick.d.ts

@@ -0,0 +1,257 @@
+import type { ApprovalGate, Envelope, GoalAutonomyState } from '@looply/core';
+import { decideAutonomyTick, type ControllerAction, type ControllerFacts, type Reconciliation } from './autonomy-controller';
+import { AutonomyStore, type AutonomyProgress } from './autonomy-store';
+import { StartAttempts, type AttemptProgress } from './start-attempts';
+import type { Publication } from './completion';
+import type { ExplicitStartDecision } from './explicit-start-gate';
+import { type RunStarter, type StartResult } from './run-launcher';
+/**
+ * ONE DAEMON TICK: LOAD FACTS, DECIDE ONCE, DO ONE THING.
+ *
+ * The impure half of the controller. It reads what is durable, hands a snapshot
+ * to the pure reducer, and carries out the single action it returns. It makes no
+ * decisions of its own — every `if` in here is about HOW to do a thing, never
+ * about WHETHER to.
+ *
+ * That split is what makes the controller testable without a filesystem and
+ * this file testable without a decision to argue with. If a policy question
+ * ever appears below, it belongs in the reducer.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ONE CONTROLLER PER TICK
+ *
+ * A daemon may hold several grants. Walking all of them and acting on each
+ * would make one tick's work unbounded and its failures interleaved. So one
+ * tick picks ONE controller and performs at most one transition for it.
+ */
+/** What the tick did, for the daemon's log and for tests to assert on. */
+export interface TickOutcome {
+    /** The controller acted on, if any was actionable. */
+    controllerId?: string;
+    action: ControllerAction | {
+        kind: 'idle';
+        because: string;
+    };
+    /** What the bounded Start seam answered, when this tick executed one. */
+    started?: StartResult;
+}
+export interface AutonomyTickDeps {
+    autonomy: AutonomyStore;
+    attempts: StartAttempts;
+    /** The bounded Start seam. The ONLY way this file causes work to happen. */
+    starter: RunStarter;
+    /**
+     * What the server says about a grant right now.
+     *
+     * Required before anything is spent, including executing an ordinal that was
+     * reserved earlier: a person can cancel in between, and a budget already
+     * spent is not permission to spend their evening too.
+     */
+    reconcile(grant: AutonomyProgress): Promise<Reconciliation>;
+    /** Whether a run has durably ended. The only thing that advances an ordinal. */
+    runEnded(runId: string): Promise<{
+        ok: true;
+        ended: boolean;
+    } | {
+        ok: false;
+        because: string;
+    }>;
+    /**
+     * Whether human authority is outstanding for this grant's pursuit.
+     *
+     * READ FROM THE SERVER, EVERY TIME, and never from anything this machine
+     * wrote down. A run that stopped for an approval records that it did — but
+     * that record is about a moment which has passed, and by now a person may
+     * have approved, denied or revoked. Believing it would hold a pursuit for
+     * ever on a question somebody answered ten minutes later.
+     *
+     * Optional so that a caller with no server behaves exactly as before. A read
+     * that FAILS must report `unknown`, not `none`: an approval nobody could see
+     * is not an approval that is not there, and only one of those two mistakes
+     * spends somebody's Start on an action they were never asked about.
+     */
+    approvalGate?(grant: AutonomyProgress): Promise<ApprovalGate>;
+    /**
+     * PROGRAMME MODE, slice 1 (M6-7). Off by default. On, and with the gate
+     * `approved`, the controller lets the Start through and this tick continues
+     * from that approval — reserved once through the same seam a person's Start
+     * uses — instead of holding for a tap.
+     */
+    programme?: boolean;
+    /**
+     * The continuation seam: the person's explicit-start decision, made for the
+     * machine's Start (`explicit-start-gate.ts`, without the person-only safety
+     * override in front of it). Answers what the Start must carry, or why it may
+     * not be made now. Absent while `programme` is on → the tick holds rather
+     * than guessing.
+     */
+    continueFrom?(gate: ApprovalGate, requestId: string, workspace: string | undefined): Promise<ExplicitStartDecision>;
+    /**
+     * Whether this machine has decided that repeating is useless.
+     *
+     * 🔴 RE-READ FROM DISK ON EVERY TICK, never cached at startup. The
+     * observations are written by the RUN process, not by the daemon, and this
+     * repository's rule for a durable fact with another writer is that it is
+     * re-read on every consultation. A daemon holding a snapshot would spend a
+     * night on a history that stopped being true after its first tick.
+     *
+     * ⚠️ AN UNREADABLE HISTORY MUST HOLD, not pass. A machine that cannot read
+     * its own safety record must not proceed on the assumption that the record is
+     * empty — that is the same mistake as reading an unreachable approval as
+     * "nobody asked", and only one of the two spends somebody's night.
+     *
+     * Optional so a caller with no store behaves exactly as before.
+     */
+    loopSafety?(grant: AutonomyProgress): Promise<{
+        readonly held: true;
+        readonly because: string;
+    } | {
+        readonly held: false;
+    }>;
+    /**
+     * A person's pending pause or stop, if one is on disk.
+     *
+     * Optional so that a caller with no control file behaves exactly as before.
+     * Absent and `null` both mean "nothing pending"; a read that FAILS should
+     * report a hold rather than nothing, because an unreadable control file is
+     * not permission.
+     */
+    humanHold?(): Promise<{
+        kind: 'pause' | 'stop';
+        actor?: string;
+    } | null>;
+    /** Durable proof that a request's run began, keyed by request id. */
+    startMarkOf(requestId: string): Promise<{
+        runId: string;
+    } | null>;
+    /** Why a request's run refused, which refusal it was, and (M5-2) on which branch. */
+    refusalOf(requestId: string): Promise<{
+        reason: string;
+        code?: string;
+        branch?: string;
+    } | null>;
+    /**
+     * THE THIRD KEY (M5-2): whether the lane has published a refused Start's
+     * branch. Optional, and absent means the key is NOT asked for — a met goal
+     * closes its grant exactly as before. The daemon supplies it only when it
+     * integrates for itself (`machine.integrate` with the lane's own
+     * `run.integration`); nothing else does.
+     *
+     * Re-read on every tick that consults it, never cached: the lane and its log
+     * are written by other processes between cadences.
+     */
+    publicationOf?(branch: string | undefined, goalId?: string): Promise<Publication>;
+    /**
+     * Tell the server where a pursuit came to rest.
+     *
+     * Returns whether the server now agrees. A failure is NOT an error to throw:
+     * the pursuit is over either way, and the only consequence of not getting
+     * through is that this tick tries again on the next cadence. Nothing about a
+     * failed projection may start another Start.
+     */
+    projectTerminal(grant: AutonomyProgress, state: GoalAutonomyState, because: string): Promise<{
+        ok: boolean;
+        because?: string;
+    }>;
+    now(): number;
+    log(line: string): void;
+    /**
+     * Rotates which actionable controller goes first.
+     *
+     * Fairness only, and deliberately not durable: a restarted daemon beginning
+     * the rotation again costs nothing, because the ORDER controllers are served
+     * in is not a fact about any of them. Without it, strict oldest-first would
+     * let one long-lived grant starve a newer one for as long as it kept having
+     * something to do.
+     */
+    rotation?: () => number;
+    /**
+     * WHICH GOALS THE SCHEDULER WOULD PREFER, BEST FIRST.
+     *
+     * 🔴 THIS IS THE SEAM THAT MAKES THE SCHEDULER REACHABLE. `decideSchedule`
+     * and `coordinatorTick` were written, specced and imported by NOTHING that
+     * ships — cycles, holds, dependency order and the anti-starvation age boost
+     * all existed and none of them could affect a single overnight decision. A
+     * scheduler nothing consults is a diagram.
+     *
+     * ⚠️ IT ORDERS, IT DOES NOT AUTHORISE. Every gate below is unchanged: the
+     * grant still has to reconcile, the approval gate still has to be clear, the
+     * safety history still has to be readable, and exactly one transition still
+     * happens per cadence. This decides WHO IS ASKED FIRST and nothing else, so
+     * the worst a wrong answer can do is waste a turn.
+     *
+     * Optional and absent by default, so a caller that does not pass it behaves
+     * exactly as before — see `machine.coordinator`.
+     */
+    prefer?: () => readonly string[];
+    /**
+     * WHAT THIS MACHINE MAY SPEND WITHOUT ASKING AGAIN, or undefined for no ceiling.
+     *
+     * 🔴 THE SEAM THAT MAKES `withinEnvelope` REACHABLE. It shipped fully specced
+     * with no production caller, no config key that could construct its input, and
+     * a spend ledger nothing read: `grep withinEnvelope(` returned one
+     * `export function` line and zero call sites.
+     *
+     * Optional and absent by default, so a caller that passes nothing behaves
+     * exactly as before and every existing project stays bounded as it was.
+     */
+    envelope?: () => Envelope | undefined;
+    /** What a Start is expected to cost, when anything can say. See `admitSpend`. */
+    estimateUsd?: () => number | undefined;
+    /** How many runs this machine has in flight, for the concurrency ceiling. */
+    runsInFlight?: () => number;
+    /** Where the machine-level spend ledger lives. Defaults to the real home. */
+    home?: string;
+    /**
+     * HOW MANY EXECUTIONS THIS CADENCE MAY LAUNCH — free capacity, `N - active`.
+     *
+     * 🔴 WITHOUT IT THE TICK LAUNCHES ONE PER CADENCE, WHICH IS A QUEUE AND NOT A
+     * FLEET. `starter.start` spawns a detached child and returns without waiting,
+     * so N launches in one cadence produce N processes running at the same
+     * instant; one per cadence fills N slots in N cadences and calls that
+     * parallelism.
+     *
+     * Optional, defaulting to 1, so every existing caller is unchanged.
+     */
+    launchesPerTick?: () => number;
+    /**
+     * WHICH CHECKOUT A GOAL SHOULD RUN IN, when a coordinator placed it.
+     *
+     * `decideSchedule` has assigned a workspace per start since it was written
+     * (`ObservedPremise.workspace`) and nothing ever carried it to the launcher.
+     * Absent means "wherever runs go by default" — the main checkout, which is
+     * where every launch has always gone.
+     */
+    workspaceFor?: (goalId: string) => string | undefined;
+    /**
+     * F28 (corr-3): what each controller asked this cadence decided — so the next cadence's
+     * scheduler gives no slot to a grant that is only waiting or holding.
+     */
+    onDecision?: (goalId: string, kind: ControllerAction['kind']) => void;
+}
+/**
+ * Do at most one thing for at most one controller.
+ *
+ * Never throws for an ordinary refusal, an unreachable server or an unreadable
+ * record: those are outcomes, and the daemon loop must not be the place they
+ * are discovered. A genuine programming error still propagates.
+ */
+export declare function autonomyTick(deps: AutonomyTickDeps): Promise<TickOutcome>;
+/**
+ * How many controllers one cadence may ASK before giving up on finding work.
+ *
+ * A ceiling rather than "all of them", so a machine holding many grants cannot
+ * turn the autonomy cadence into an unbounded sweep every ten seconds. Six is
+ * comfortably more than the number of goals a person pursues at once and small
+ * enough that the worst tick is still a handful of file reads and one HTTP GET
+ * per candidate.
+ *
+ * Being wrong low is harmless: the rotation moves on, so a controller missed
+ * this cadence is asked on the next one. Being wrong high costs work every ten
+ * seconds for ever.
+ */
+export declare const MAX_CONTROLLERS_PER_TICK = 6;
+/** Re-exported so the daemon wires one name rather than three. */
+export { decideAutonomyTick, type ControllerAction, type ControllerFacts, type Reconciliation };
+export type { AttemptProgress, StartAttempts, AutonomyStore };
+//# sourceMappingURL=autonomy-tick.d.ts.map

package/dist/autonomy-tick.d.ts.map

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