@amalgm/shell 0.1.164-preview.36072132286 → 0.1.164-preview.36809057014

package/dist/turns.js

@@ -0,0 +1,112 @@
+/**
+ * One main-thread dispatcher for the rails' ready continuations: Detect,
+ * Send, Receive, Apply and cache maintenance. Each activation runs the oldest
+ * queued chunk, then returns to the event loop before the next, so ready work
+ * from several rails never runs back to back in one check phase. Asynchronous
+ * work never occupies it: a chunk that needs I/O starts that I/O and ends, and
+ * the completion queues the next chunk.
+ *
+ * It orders only these continuations. I/O callbacks, native completions,
+ * promise continuations, garbage collection and unrelated callbacks still run
+ * around it, and a chunk is only as short as the work its owner put in it.
+ */
+import { eachStep } from "@amalgm/live";
+const turns = [];
+/** Synchronous work one activation may run before a long preparation takes
+ * a later activation at its next boundary: well inside the 10 ms stall
+ * ceiling, so the step past a boundary still fits. */
+const TURN_BUDGET_MS = 4;
+let activation = 0;
+function runTurn() {
+    const chunk = turns.shift();
+    if (turns.length > 0)
+        setImmediate(runTurn);
+    activation = performance.now();
+    chunk();
+}
+/** Run `chunk` in a later dispatcher activation; never inline. */
+export function queueTurn(chunk) {
+    turns.push(chunk);
+    // An immediate queued from an I/O callback runs before this iteration's
+    // timers, so the first chunk hops once more to wait a full turn like the rest.
+    if (turns.length === 1)
+        setImmediate(() => setImmediate(runTurn));
+}
+/** Resume the caller in its own activation: pending I/O, timers and wire
+ * frames run first. */
+export function awaitTurn() {
+    return new Promise((resolve) => queueTurn(resolve));
+}
+/** An already-valid boundary in a long preparation: continue while this
+ * activation is within its budget, else resume in a later one. Work resumed
+ * outside the dispatcher counts from the last activation, so it joins the
+ * dispatcher at its first boundary. */
+export async function turnBoundary() {
+    if (performance.now() - activation >= TURN_BUDGET_MS)
+        await awaitTurn();
+}
+/** Visit every item of a long synchronous pass in order, taking a later
+ * activation once this one has spent its budget. */
+export function eachInTurns(items, visit) {
+    return finishStepsInTurns(eachStep(items, visit));
+}
+/** Every item's image, in order, as eachInTurns visits them. */
+export async function mapInTurns(items, image) {
+    const images = [];
+    await eachInTurns(items, item => { images.push(image(item)); });
+    return images;
+}
+/** Start each item's effect in order, taking a later activation once this
+ * one has spent its budget, and answer every result in order once every
+ * started effect has settled; the first failure in order fails the whole.
+ * An effect's synchronous preparation counts against the activation that
+ * starts it, so no number of items starts in one. */
+export async function settleInTurns(items, start) {
+    const outcomes = [];
+    for (const item of items) {
+        await turnBoundary();
+        // Observed as it starts: a failure while later effects start is never unhandled.
+        outcomes.push(start(item).then((value) => ({ status: "fulfilled", value }), (reason) => ({ status: "rejected", reason })));
+    }
+    const settled = await Promise.all(outcomes);
+    const failure = settled.find((outcome) => outcome.status === "rejected");
+    if (failure)
+        throw failure.reason;
+    return settled.map(outcome => outcome.value);
+}
+/** The parts joined in order into one buffer, one part copied per step. */
+export async function concatInTurns(parts) {
+    let length = 0;
+    for (const part of parts)
+        length += part.byteLength;
+    const joined = Buffer.allocUnsafe(length);
+    let at = 0;
+    for (const part of parts) {
+        joined.set(part, at);
+        at += part.byteLength;
+        await turnBoundary();
+    }
+    return joined;
+}
+/** Live's steps on the main thread, taking a later activation at a boundary
+ * once this one has spent its budget. */
+export async function finishStepsInTurns(steps) {
+    for (let next = steps.next();; next = steps.next()) {
+        if (next.done)
+            return next.value;
+        await turnBoundary();
+    }
+}
+/** A host effect a rail awaits. Its answer or failure reaches the rail in a
+ * dispatcher activation, never inline in the callback that completed the I/O. */
+export function resumeInTurn(effect) {
+    return async (...args) => {
+        try {
+            return await effect(...args);
+        }
+        finally {
+            await awaitTurn();
+        }
+    };
+}
+//# sourceMappingURL=turns.js.map

package/dist/turns.js.map

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

package/dist/updates/bootstrap.d.ts

@@ -1,15 +1,30 @@
+/** Stable installation-owned process effect. This compiled module is copied
+ * outside immutable package generations, so every runtime import is a Node
+ * builtin. Core's controller writes release decisions and recovery commands;
+ * this launcher only reserves and performs those already-declared effects.
+ * Because it can import nothing else, it also owns the builtin-only
+ * supervision rules the keepalive controller reuses: backoff and liveness. */
+import { type ChildProcess } from 'node:child_process';
+/** Raised with every change to launcher behavior. Controllers install a newer
+ * launcher file; a running launcher that finds a newer file exits at its next
+ * controller boundary so its OS owner starts the new one. */
+export declare const BOOTSTRAP_REVISION = 2;
+/** The exit status (EX_TEMPFAIL) that asks the OS owner for the new launcher. */
+export declare const BOOTSTRAP_UPGRADED_EXIT = 75;
 export interface LaunchCommand {
     node: string;
     bin: string;
     args: string[];
 }
 export interface LaunchLimits {
+    /** Read only by revision-1 launchers, which park after this many launches. */
     maxAttempts: number;
     initialDelayMs: number;
     maxDelayMs: number;
     stableAfterMs: number;
     readyTimeoutMs: number;
     healthIntervalMs: number;
+    /** Read only by revision-1 launchers, which ignore a later answer. */
     healthTimeoutMs: number;
     maxHealthFailures: number;
     stopGraceMs: number;
@@ -27,8 +42,9 @@ export interface LaunchState extends LaunchLimits {
     attempts: number;
 }
 export declare function validateLaunchState(value: unknown): LaunchState;
-/** Reinstall can repair a missing bootstrap file, but never resets selected
- * release, in-flight handover, or spent recovery allowance. */
+/** Install writes the first launch. Every later install and every controller
+ * start brings the launcher file and its limits forward; neither changes the
+ * selected release, an in-flight handover or the current backoff. */
 export declare function initializeBootstrap(input: {
     serviceDir: string;
     controllerLease: string;
@@ -40,9 +56,39 @@ export declare function initializeBootstrap(input: {
     args: string[];
     current: LaunchCommand;
 };
-/** Explicit operator retry restores control through known recovery code. It
- * never chooses the failed candidate or changes the Core policy/quarantine. */
-export declare function retryBootstrap(databaseFile: string): boolean;
-/** One stable owner waits for the installation lease to drain, charges every
- * launch durably, and parks rather than asking its OS parent for more attempts. */
+/** A running controller applies its policy to an installed launcher. */
+export declare function refreshBootstrap(serviceDir: string, limits: LaunchLimits): void;
+/** A missing launcher is revision 0; the first copied launcher carried no mark. */
+export declare function bootstrapRevision(file: string): number;
+/** Consecutive unhealthy starts double the wait before the next one until it
+ * reaches the ceiling. There is no last attempt. */
+export declare function backoffMs(limits: {
+    initialDelayMs: number;
+    maxDelayMs: number;
+}, attempts: number): number;
+/** Operator retry cuts the current backoff short. It never selects a failed
+ * candidate or changes Core's policy or quarantine. */
+export declare function retryBootstrap(databaseFile: string): void;
+/** One launcher per installation keeps one controller running while the
+ * machine is on. It exits only when its OS owner stops it (0), when the
+ * operator stops the controller (0), or when a newer launcher is installed
+ * (75); it relaunches every other controller exit after a capped backoff. */
 export declare function runBootstrap(databaseFile: string, controllerLeaseFile: string): Promise<number>;
+export interface LivenessLimits {
+    intervalMs: number;
+    misses: number;
+    readyDeadlineMs: number;
+    stableAfterMs: number;
+}
+/** Silence, not slowness, is death. A supervisor asks its child every
+ * interval; an answer to any outstanding question, however late, proves the
+ * child alive and clears every miss. The child is dead only after `misses`
+ * consecutive checks found it silent, and a check counts only when it ran on
+ * time: a supervisor that was itself suspended or starved saw nothing. Misses
+ * count from the child's first sign of life, so a child that answers only once
+ * ready is bounded by its ready deadline until then. Returns the unwatch. */
+export declare function watchLiveness(child: ChildProcess, limits: LivenessLimits, effects: {
+    ready?(): void;
+    stable(): void;
+    failed(reason: string): void;
+}): () => void;