@cat-factory/kernel 0.329.0 → 0.331.0

package/dist/domain/environment-reachability.logic.d.ts

@@ -1,4 +1,5 @@
-import type { EnvironmentAddress, EnvironmentRouteAttempt, EnvironmentRouteProof, EnvironmentUnreachableReason } from '@cat-factory/contracts';
+import type { EnvironmentRouteCandidate, EnvironmentRouteAttempt, EnvironmentRouteProof, EnvironmentUnreachableReason } from '@cat-factory/contracts';
+import type { HostResolveOutcome } from '../ports/host-resolver.js';
 import type { RouteProbeOutcome, RouteProbeRequest } from '../ports/route-probe.js';
 /** How long one target gets before it counts as a route that does not carry. */
 export declare const ROUTE_PROBE_TIMEOUT_MS = 4000;
@@ -12,53 +13,121 @@ export declare const ROUTE_PROBE_TIMEOUT_MS = 4000;
  * 162ms, so the ceiling is well under a second of ordinary cost.
  */
 export declare const MAX_PROBED_ADDRESSES = 4;
+/**
+ * How long one stated NAME gets to resolve before the lookup counts as one the platform could not
+ * complete.
+ *
+ * Much tighter than {@link ROUTE_PROBE_TIMEOUT_MS}, because the two wait on different things: a
+ * connect legitimately hangs against a route that does not carry, which is the finding, whereas a
+ * resolver that has not answered in two seconds is not about to.
+ */
+export declare const HOST_RESOLVE_TIMEOUT_MS = 2000;
+/**
+ * How many stated NAMES a proof will look up.
+ *
+ * Its own bound rather than a share of {@link MAX_PROBED_ADDRESSES}, because they cap different
+ * costs: that one caps sockets opened, this one caps lookups made, and one name can expand into
+ * several addresses so neither implies the other. The same four, sized for the same shape (an
+ * internal and a public balancer, with room for a second availability zone).
+ */
+export declare const MAX_RESOLVED_HOSTS = 4;
+/**
+ * The stated NAMES a proof will resolve, in the provider's order, deduplicated and bounded.
+ *
+ * Exported because the caller does the I/O and the plan consumes the answers, so both have to
+ * agree about exactly which names are in scope. Stated ONCE here and read twice rather than
+ * recomputed on each side: two copies of a bound is how a name beyond it comes to be reported as a
+ * name nothing could resolve.
+ */
+export declare function planHostResolutions(candidates?: readonly EnvironmentRouteCandidate[]): string[];
 /**
  * One target a proof will try, in the order the proof will try it.
  *
- * A discriminated union rather than a dial target with a "skip me" flag, because the refused
- * member carries NO {@link RouteProbeRequest}: an address the platform will not dial must be
- * structurally undialable by whoever iterates this list, not merely marked. Handing out a request
- * beside a boolean is how the next caller opens the socket anyway.
+ * A discriminated union rather than a dial target with a "skip me" flag, because the second member
+ * carries NO {@link RouteProbeRequest}: a target the platform will not dial must be structurally
+ * undialable by whoever iterates this list, not merely marked. Handing out a request beside a
+ * boolean is how the next caller opens the socket anyway.
+ *
+ * ONE undialled member rather than one per cause, because the callers do the same thing with all
+ * of them (record the attempt, move on) and the cause they differ by is already the
+ * {@link EnvironmentUnreachableReason} each carries.
  */
 export type RouteProbeTarget = 
-/** Open a socket to this. `address` is null when the target dials the URL's own name. */
+/**
+ * Open a socket to this. `address` is null when the target dials the URL's own name, and
+ * `statedHost` is set when the address came from RESOLVING a stated name rather than from a
+ * stated address, so a proof can publish which candidate carried and not merely which literal.
+ */
 {
     kind: 'dial';
     request: RouteProbeRequest;
     address: string | null;
+    statedHost?: string;
     label: string;
 }
-/** RECORD this and dial nothing: a stated address {@link isBridgeableAddress} refuses. */
+/**
+ * RECORD this and dial nothing: an address {@link isBridgeableAddress} refuses, a candidate
+ * naming no single target, a stated name that resolved nowhere, and a stated name this
+ * deployment has nothing to resolve with.
+ */
  | {
-    kind: 'refused';
-    address: string;
+    kind: 'undialled';
     label: string;
     reason: EnvironmentUnreachableReason;
+    detail?: string;
 };
+/** What {@link planRouteProbes} needs beyond the candidate list itself. */
+export interface RouteProbePlan {
+    /**
+     * What the platform's resolver answered for each name {@link planHostResolutions} named, keyed
+     * by that same normalized name.
+     *
+     * A name IN that plan with no entry here means nothing was wired to resolve it, which is an
+     * admission about the deployment and is recorded as one. A name beyond the plan's bound is not
+     * in scope and is passed over, exactly as an address beyond the dial bound is.
+     */
+    resolutions?: ReadonlyMap<string, HostResolveOutcome>;
+    timeoutMs?: number;
+}
 /**
  * The targets a proof tries for one environment, in order: the URL's own name first, then each
- * stated address in the PROVIDER'S preference order.
- *
- * The name goes first because it is the answer that needs no bridge, and a deployment where it
- * works must not start paying for `--add-host` entries and the warm-pool evictions they cost. The
- * addresses keep the provider's order because the provider is the only thing that knows which of
- * its balancers is the one it wants used; the platform decides only which one CARRIED.
- *
- * **A stated address is dialled only if a bridge could NAME it.** The rule is
- * `isBridgeableAddress`, and applying it HERE rather than only at bridge-build time is the whole
- * safety property of the probe: `addresses` is provider-authored data, so without it the
- * orchestrator opens sockets wherever a manifest says and records the results on a row a workspace
- * can read back, which is a liveness oracle against the deployment's own private network. The
- * refusal costs nothing real either, because an address no bridge may name is an address no
- * container could be pointed at, so proving it would prove something unusable. Refused addresses
- * are RECORDED (`kind: 'refused'`) rather than dropped: a shortened list nobody is told about is
- * how a provider's bad address becomes an unexplained `name_unresolved`.
+ * stated candidate in the PROVIDER'S preference order, a stated NAME expanded IN PLACE into the
+ * addresses it resolved to.
+ *
+ * The URL's name goes first because it is the answer that needs no bridge, and a deployment where
+ * it works must not start paying for `--add-host` entries and the warm-pool evictions they cost.
+ * The candidates keep the provider's order because the provider is the only thing that knows which
+ * of its balancers is the one it wants used; the platform decides only which one CARRIED. A name is
+ * expanded in place rather than having its addresses appended, so that order still means something
+ * when a provider states a name and an address side by side.
+ *
+ * **Every dialled target is an address a bridge could NAME**, whether the provider stated it or the
+ * platform resolved it. The rule is `isBridgeableAddress`, and applying it HERE rather than only at
+ * bridge-build time is the whole safety property of the probe: candidates are provider-authored
+ * data, so without it the orchestrator opens sockets wherever a manifest says and records the
+ * results on a row a workspace can read back, which is a liveness oracle against the deployment's
+ * own private network. Resolving first and grading each answer is what keeps that property intact
+ * for a name: the destination a bridge is built from is still an IP the platform itself proved, and
+ * a name answering with something unbridgeable is refused per address.
+ *
+ * The refusal costs nothing real either, because an address no bridge may name is an address no
+ * container could be pointed at, so proving it would prove something unusable. Refused and
+ * unresolvable targets are RECORDED (`kind: 'undialled'`) rather than dropped: a shortened list
+ * nobody is told about is how a provider's bad candidate becomes an unexplained `name_unresolved`.
+ *
+ * **Every cap this plan applies reports what it passed over**, in one final `not_attempted`
+ * target. Three of them bite (names beyond {@link MAX_RESOLVED_HOSTS}, addresses beyond the dial
+ * budget, records beyond the recording budget) and each ends the list early, so without that
+ * report a proof over a longer list is a prefix presented as the whole thing. It is not a
+ * cosmetic omission: {@link reduceRouteProof} grades `not_reached` only when every attempt
+ * established something, and a silently shortened list is how the deployer comes to fail a frame
+ * on a verdict about candidates the platform never looked at.
  *
  * Empty when there is no host or port to dial, which the caller reads as `no_candidate`: an
  * environment with no URL was never going to be reached, and that is a different fact from one
  * that was tried and failed.
  */
-export declare function planRouteProbes(host: string | null | undefined, port: number | null | undefined, candidates?: readonly EnvironmentAddress[], timeoutMs?: number): RouteProbeTarget[];
+export declare function planRouteProbes(host: string | null | undefined, port: number | null | undefined, candidates?: readonly EnvironmentRouteCandidate[], plan?: RouteProbePlan): RouteProbeTarget[];
 /**
  * Record one DIALLED attempt for the proof's log, whether it carried or not.
  *
@@ -70,10 +139,27 @@ export declare function planRouteProbes(host: string | null | undefined, port: n
 export declare function recordRouteAttempt(target: Extract<RouteProbeTarget, {
     kind: 'dial';
 }>, outcome: RouteProbeOutcome): EnvironmentRouteAttempt;
-/** Record a target the platform REFUSED to dial, so the omission is on the proof rather than lost. */
-export declare function recordRefusedAttempt(target: Extract<RouteProbeTarget, {
-    kind: 'refused';
+/**
+ * Record a target the platform never DIALLED, so the omission is on the proof rather than lost.
+ *
+ * Carries the same `detail` a dialled attempt does, because one of the causes that lands here says
+ * nothing on its own: a lookup that failed rather than answering nothing is `probe_failed`, and
+ * without the resolver's own words a reader cannot tell a DNS timeout from a resolver outage from a
+ * bug in the adapter.
+ */
+export declare function recordUndialledAttempt(target: Extract<RouteProbeTarget, {
+    kind: 'undialled';
 }>): EnvironmentRouteAttempt;
+/**
+ * The target that carried, as {@link reduceRouteProof} publishes it: the address, plus the stated
+ * NAME it was resolved from when it came from one.
+ *
+ * The dial target's own shape, so the caller passes what it already has rather than picking two
+ * fields apart. Null for a proof where nothing carried, where `via` is null for the other reason.
+ */
+export type CarryingTarget = Pick<Extract<RouteProbeTarget, {
+    kind: 'dial';
+}>, 'address' | 'statedHost'>;
 /**
  * Fold a completed set of attempts into the proof that is stored and narrated.
  *
@@ -82,16 +168,17 @@ export declare function recordRefusedAttempt(target: Extract<RouteProbeTarget, {
  *
  *   - **`reached`** as soon as any attempt carried, publishing the target that did.
  *   - **`inconclusive`** when nothing carried AND some attempt left a route unruled-out: a probe
- *     that could not classify its own failure, or nothing to try at all. A workerd connect message
- *     matching none of that facade's markers, or a Node errno outside the mapped five, arrives
- *     here, and reading either as a verdict about the environment is how a diagnostic becomes a
- *     second way for a healthy deploy to die. The reason names the attempt that left it unknown.
+ *     that could not classify its own failure, a candidate the plan passed over, or nothing to try
+ *     at all. A workerd connect message matching none of that facade's markers, or a Node errno
+ *     outside the mapped five, arrives here, and reading either as a verdict about the environment
+ *     is how a diagnostic becomes a second way for a healthy deploy to die. The reason names the
+ *     attempt that left it unknown.
  *   - **`not_reached`** only when EVERY attempt established something and none of them carried.
  *     The reported reason is then the FIRST attempt's, which is always the name, so a reader is
  *     told what happened to the address they were given rather than what happened to the last
  *     balancer in someone's preference list. The attempt log carries the rest, in order.
  */
-export declare function reduceRouteProof(attempts: readonly EnvironmentRouteAttempt[], carriedVia: string | null, checkedAt: number): EnvironmentRouteProof;
+export declare function reduceRouteProof(attempts: readonly EnvironmentRouteAttempt[], carried: CarryingTarget | null, checkedAt: number): EnvironmentRouteProof;
 /**
  * The operator-facing sentence for an environment nothing could reach, with every target tried.
  *
@@ -147,7 +234,7 @@ export declare function describeRouteTargets(attempts: readonly EnvironmentRoute
  * because it is an admission about the platform and naming it a cause is how "we could not tell"
  * comes to read as a verdict.
  */
-export declare function determinateRouteCause(candidates: readonly EnvironmentAddress[], proof: EnvironmentRouteProof | null): string | null;
+export declare function determinateRouteCause(candidates: readonly EnvironmentRouteCandidate[], proof: EnvironmentRouteProof | null): string | null;
 /**
  * The proof recorded when nothing was wired to open a socket.
  *

package/dist/domain/environment-reachability.logic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"environment-reachability.logic.d.ts","sourceRoot":"","sources":["../../src/domain/environment-reachability.logic.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EACV,kBAAkB,EAClB,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,EAC7B,MAAM,wBAAwB,CAAA;AAE/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAA;AAMnF,gFAAgF;AAChF,eAAO,MAAM,sBAAsB,OAAO,CAAA;AAE1C;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAErC;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB;AAC1B,yFAAyF;AACvF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,iBAAiB,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AACrF,0FAA0F;GACxF;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,4BAA4B,CAAA;CAAE,CAAA;AAE7F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC/B,UAAU,GAAE,SAAS,kBAAkB,EAAO,EAC9C,SAAS,GAAE,MAA+B,GACzC,gBAAgB,EAAE,CA4BpB;AA8BD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EACnD,OAAO,EAAE,iBAAiB,GACzB,uBAAuB,CAQzB;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,CAAC,gBAAgB,EAAE;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC,GACrD,uBAAuB,CAEzB;AAwCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,SAAS,EAAE,MAAM,GAChB,qBAAqB,CA6BvB;AAcD;;;;;;;;;GASG;AACH,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAKR;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAKR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,SAAS,uBAAuB,EAAE,GAAG,MAAM,CAOzF;AAQD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,SAAS,kBAAkB,EAAE,EACzC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAClC,MAAM,GAAG,IAAI,CAwCf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,qBAAqB,CAEtE"}
+{"version":3,"file":"environment-reachability.logic.d.ts","sourceRoot":"","sources":["../../src/domain/environment-reachability.logic.ts"],"names":[],"mappings":"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"}