@groundnuty/macf-core 0.2.44 → 0.2.45

package/dist/verify-green.d.ts

@@ -0,0 +1,62 @@
+import type { HealthResponse } from './types.js';
+/** Default poll interval between `probe` attempts (ms). */
+export declare const DEFAULT_VERIFY_GREEN_INTERVAL_MS = 2000;
+/** Inputs to `verifyGreen`. */
+export interface VerifyGreenOptions {
+    /** The agent (routing label) to verify — passed straight to `probe`. */
+    readonly agent: string;
+    /** The version the agent must self-report to be considered green. */
+    readonly targetVersion: string;
+    /** Total wall-time budget before giving up (ms). */
+    readonly timeoutMs: number;
+    /** Poll interval between attempts (ms; default `DEFAULT_VERIFY_GREEN_INTERVAL_MS`). */
+    readonly intervalMs?: number;
+}
+/**
+ * Injectable seams for `verifyGreen` — keeps it a pure function of its inputs
+ * (no clock, no network, no timers baked in), so it's unit-testable with a fake
+ * probe sequence + a virtual clock.
+ */
+export interface VerifyGreenDeps {
+    /**
+     * Re-resolve the agent's CURRENT registry endpoint and probe its `/health`.
+     * Returns the parsed body, or `null` when unreachable (offline / mid-restart /
+     * endpoint not yet re-advertised). MUST re-read the registry each call so a
+     * restart-self port churn is picked up (DR-037 Decision 5).
+     */
+    readonly probe: (agent: string) => Promise<HealthResponse | null>;
+    /** Sleep `ms` between poll attempts (injected so tests don't wait). */
+    readonly sleep: (ms: number) => Promise<void>;
+    /** Monotonic-ish clock in ms (injected so tests drive the timeout). */
+    readonly now: () => number;
+}
+/**
+ * The terminal outcome of a `verifyGreen` poll.
+ *
+ * - `ok: true`  — the agent self-reported the target version; `version` echoes it.
+ * - `ok: false` + `reason: 'wrong-version'` — the agent was REACHABLE within the
+ *   budget but never at the target (`lastVersion` is the last version seen, or
+ *   `null` if a reachable body carried no version). The common mid-restart case
+ *   that never converges (bad pin / stuck old process).
+ * - `ok: false` + `reason: 'unreachable'` — the agent was NEVER reachable within
+ *   the budget (every probe returned `null`). The dead / never-relaunched case.
+ */
+export type VerifyGreenResult = {
+    readonly ok: true;
+    readonly version: string;
+} | {
+    readonly ok: false;
+    readonly reason: 'wrong-version' | 'unreachable';
+    readonly lastVersion: string | null;
+};
+/**
+ * Poll `deps.probe(agent)` until the agent self-reports `targetVersion`
+ * (via `compareSemver === 0`) or the `timeoutMs` budget is exhausted.
+ *
+ * Guarantees at least one probe (even with `timeoutMs === 0`), then checks the
+ * elapsed budget BEFORE each `sleep`, so the loop always terminates. The
+ * version comparison uses `compareSemver` (macf-core, macf#424) so a leading
+ * `v` / normalization is handled consistently with the rest of the fleet.
+ */
+export declare function verifyGreen(opts: VerifyGreenOptions, deps: VerifyGreenDeps): Promise<VerifyGreenResult>;
+//# sourceMappingURL=verify-green.d.ts.map

package/dist/verify-green.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-green.d.ts","sourceRoot":"","sources":["../src/verify-green.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,2DAA2D;AAC3D,eAAO,MAAM,gCAAgC,OAAO,CAAC;AAErD,+BAA+B;AAC/B,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IAClE,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,uEAAuE;IACvE,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/C;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC,CAAC;AAEN;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,kBAAkB,EACxB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,iBAAiB,CAAC,CAyB5B"}

package/dist/verify-green.js

@@ -0,0 +1,53 @@
+/**
+ * `verifyGreen` — the shared post-restart health-and-version gate (DR-037
+ * Decision 5). Both the rolling-upgrade sequencer and the reconcile loop need it:
+ * after a `driver.restart(agent)`, confirm the agent came back REACHABLE at the
+ * TARGET version before proceeding to the next agent (upgrade) or clearing the
+ * heal (reconcile).
+ *
+ * Pure + runtime-agnostic (macf-core, DR-037 OQ2). It takes an injectable
+ * "re-resolve + probe" callback and polls-with-timeout. The **re-resolve is the
+ * caller's job, inside `probe`** — `restart-self` relaunches with a NEW port +
+ * instance_id (DR-037 Decision 5), so a correct `probe(agent)` MUST re-read the
+ * registry for the FRESH endpoint on each call and never reuse the dead
+ * pre-restart `host:port` (a silent-fallback trap: a stale endpoint returns
+ * `null` forever → a false "not-green"). `verifyGreen` itself only polls that
+ * callback + applies the version check via macf-core's `compareSemver`.
+ */
+import { compareSemver } from './semver.js';
+/** Default poll interval between `probe` attempts (ms). */
+export const DEFAULT_VERIFY_GREEN_INTERVAL_MS = 2000;
+/**
+ * Poll `deps.probe(agent)` until the agent self-reports `targetVersion`
+ * (via `compareSemver === 0`) or the `timeoutMs` budget is exhausted.
+ *
+ * Guarantees at least one probe (even with `timeoutMs === 0`), then checks the
+ * elapsed budget BEFORE each `sleep`, so the loop always terminates. The
+ * version comparison uses `compareSemver` (macf-core, macf#424) so a leading
+ * `v` / normalization is handled consistently with the rest of the fleet.
+ */
+export async function verifyGreen(opts, deps) {
+    const intervalMs = opts.intervalMs ?? DEFAULT_VERIFY_GREEN_INTERVAL_MS;
+    const start = deps.now();
+    let reachedOnce = false;
+    let lastVersion = null;
+    for (;;) {
+        const health = await deps.probe(opts.agent);
+        if (health) {
+            reachedOnce = true;
+            lastVersion = health.version ?? null;
+            if (lastVersion !== null && compareSemver(lastVersion, opts.targetVersion) === 0) {
+                return { ok: true, version: lastVersion };
+            }
+        }
+        if (deps.now() - start >= opts.timeoutMs) {
+            return {
+                ok: false,
+                reason: reachedOnce ? 'wrong-version' : 'unreachable',
+                lastVersion,
+            };
+        }
+        await deps.sleep(intervalMs);
+    }
+}
+//# sourceMappingURL=verify-green.js.map

package/dist/verify-green.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-green.js","sourceRoot":"","sources":["../src/verify-green.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,gCAAgC,GAAG,IAAI,CAAC;AAoDrD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,IAAwB,EACxB,IAAqB;IAErB,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,gCAAgC,CAAC;IACvE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,WAAW,GAAkB,IAAI,CAAC;IAEtC,SAAS,CAAC;QACR,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QAC5C,IAAI,MAAM,EAAE,CAAC;YACX,WAAW,GAAG,IAAI,CAAC;YACnB,WAAW,GAAG,MAAM,CAAC,OAAO,IAAI,IAAI,CAAC;YACrC,IAAI,WAAW,KAAK,IAAI,IAAI,aAAa,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;YAC5C,CAAC;QACH,CAAC;QAED,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACzC,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,aAAa;gBACrD,WAAW;aACZ,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAC/B,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundnuty/macf-core",
-  "version": "0.2.44",
+  "version": "0.2.45",
   "description": "Shared internals consumed by the MACF CLI and channel-server packages. Not intended for direct external use — will be marked deprecated-internal on first npm publish per DR-022 Amendment A.",
   "type": "module",
   "main": "dist/index.js",