@cat-factory/contracts 0.336.0 → 0.337.0

package/dist/environment-reachability.d.ts

@@ -0,0 +1,246 @@
+import * as v from 'valibot';
+/**
+ * One address a provider states will carry traffic for its environment's URL host.
+ *
+ * The motivating shape is an org running per-PR preview environments whose per-environment DNS
+ * record lives in an internal view while the load balancers fronting it are ordinary names and
+ * the ingress routes on the `Host` header. The address exists and a container's egress reaches
+ * it. The only missing thing is a name-to-address mapping, which is exactly what a hosts-file
+ * entry (or a Kubernetes `hostAliases` entry) is.
+ *
+ * `label` is for the human reading a diagnostic ("internal ALB", "public ALB"), never for
+ * matching: the platform picks by PROBING, never by name.
+ */
+export declare const environmentAddressSchema: v.ObjectSchema<{
+    /** An IP literal. Never a name: a name would just be the lookup that already failed. */
+    readonly address: v.StringSchema<undefined>;
+    /** What this address IS, for the diagnostic. Never load-bearing. */
+    readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type EnvironmentAddress = v.InferOutput<typeof environmentAddressSchema>;
+/**
+ * Why a `ready` environment could not be reached, at the layer the platform can observe.
+ *
+ * Separate members rather than one "unreachable" because they need different reactions and name
+ * different owners: `name_unresolved` with candidates that also failed is an environment nobody
+ * can reach, `no_candidate` is a PROVIDER that never told us where the thing lives, and
+ * `connection_refused` is a route that carries to a box with nothing listening, which is the
+ * deployed workload rather than the network.
+ *
+ *  - `no_candidate`       the environment carries no URL, or one with no host to probe. There
+ *                         was nothing to try, which is not the same as trying and failing.
+ *  - `name_unresolved`    the URL's host resolved nowhere, and no stated address carried either.
+ *  - `no_route`           something resolved and the connect never completed (timeout,
+ *                         host/network unreachable). The expensive failure: a lookup that
+ *                         worked followed by a connect that hangs.
+ *  - `connection_refused` the route carries and nothing is listening on the port.
+ *  - `address_refused`    the provider stated an address the platform will not dial: loopback,
+ *                         link-local/vendor metadata, or a non-canonical literal. Recorded as an
+ *                         attempt rather than dropped, because a refused input is an omission the
+ *                         operator has to be able to see.
+ *  - `probe_failed`       the probe itself errored in a way it could not classify. Kept apart
+ *                         from the three above so "we could not tell" never renders as a
+ *                         verdict about the environment.
+ */
+export declare const environmentUnreachableReasonSchema: v.PicklistSchema<["no_candidate", "name_unresolved", "no_route", "connection_refused", "address_refused", "probe_failed"], undefined>;
+export type EnvironmentUnreachableReason = v.InferOutput<typeof environmentUnreachableReasonSchema>;
+/** One target the proof tried, in the order it was tried, and what came back. */
+export declare const environmentRouteAttemptSchema: v.ObjectSchema<{
+    /** `host:port` for the name itself, `host@address:port` for a stated address. */
+    readonly target: v.StringSchema<undefined>;
+    /** `carried`, or the {@link EnvironmentUnreachableReason} that target produced. */
+    readonly outcome: v.StringSchema<undefined>;
+    /**
+     * What the probe said when it could not classify its own failure, capped for a rendered
+     * surface. The ONLY field carrying WHY a `probe_failed` attempt failed.
+     *
+     * Kept because `probe_failed` names no layer by design, so without this an operator reading a
+     * proof cannot tell a TLS or resolver fault from a runtime restriction from a bug in the probe:
+     * the three need different fixes and the reason renders identically for all of them. Absent for
+     * every other outcome, which is already self-describing.
+     */
+    readonly detail: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+export type EnvironmentRouteAttempt = v.InferOutput<typeof environmentRouteAttemptSchema>;
+/**
+ * What the platform PROVED about reaching an environment, once, at the moment it went `ready`.
+ *
+ * `state` splits along TWO axes and both are load-bearing. `reached` and `not_reached` are
+ * verdicts about the ENVIRONMENT, and only `not_reached` fails a deployer frame. `inconclusive`
+ * and `unproved` are verdicts about the PLATFORM, and neither may ever fail anything: collapsing
+ * either into `not_reached` turns a diagnostic into a second way for a healthy deploy to die,
+ * which is the one failure mode this whole module must not introduce, and collapsing either into
+ * `reached` hands a tester the unbacked claim it exists to retire.
+ *
+ *   - `inconclusive` the platform LOOKED and established nothing either way: a probe that
+ *                    errored in a way it could not classify, or an environment with no address to
+ *                    dial. Narrated, because "we could not tell" is exactly the fact that stops an
+ *                    agent concluding the environment is dead.
+ *   - `unproved`     nothing was wired to open a socket, so nothing was tried. SILENT (see
+ *                    {@link reachabilityNote}): it is the standing state of every deployment with
+ *                    no prober, and a line on every prompt is a line nobody reads on the one
+ *                    prompt where it matters.
+ */
+export declare const environmentRouteProofSchema: v.ObjectSchema<{
+    readonly state: v.PicklistSchema<["reached", "not_reached", "inconclusive", "unproved"], undefined>;
+    /**
+     * The stated address that CARRIED, or null when the URL's own name carried (the ordinary case)
+     * and when nothing carried at all. Read `state` to tell those two apart.
+     *
+     * This is the field a container bridge is built from, which is why the proof publishes the
+     * candidate that carried rather than the first that resolved: a bridge built from an unproved
+     * address is recorded as successfully applied while the tester still fails, and the evidence
+     * then points further from the cause than no bridge at all did.
+     */
+    readonly via: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /**
+     * The {@link EnvironmentUnreachableReason} when `state` is `not_reached` or `inconclusive`,
+     * else null. An open string on the wire so a stored proof written by an older build never fails
+     * to parse; readers that branch on it treat an unknown value as "not one of the cases I handle".
+     */
+    readonly reason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** Every target tried, in order. Recorded whether or not one carried. */
+    readonly attempts: v.ArraySchema<v.ObjectSchema<{
+        /** `host:port` for the name itself, `host@address:port` for a stated address. */
+        readonly target: v.StringSchema<undefined>;
+        /** `carried`, or the {@link EnvironmentUnreachableReason} that target produced. */
+        readonly outcome: v.StringSchema<undefined>;
+        /**
+         * What the probe said when it could not classify its own failure, capped for a rendered
+         * surface. The ONLY field carrying WHY a `probe_failed` attempt failed.
+         *
+         * Kept because `probe_failed` names no layer by design, so without this an operator reading a
+         * proof cannot tell a TLS or resolver fault from a runtime restriction from a bug in the probe:
+         * the three need different fixes and the reason renders identically for all of them. Absent for
+         * every other outcome, which is already self-describing.
+         */
+        readonly detail: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** When the proof ran (epoch ms). */
+    readonly checkedAt: v.NumberSchema<undefined>;
+}, undefined>;
+export type EnvironmentRouteProof = v.InferOutput<typeof environmentRouteProofSchema>;
+/**
+ * Everything the platform knows about ADDRESSING an environment, beside the one string it knows
+ * about naming it.
+ *
+ * Two halves because they come from two places and one of them is a claim: `candidates` is what
+ * the PROVIDER said, `proof` is what the platform TRIED. Keeping the claim after the proof runs
+ * is deliberate: an operator debugging a dead environment wants to see which addresses were
+ * offered as well as which were reached, and a re-probe on a later poll re-reads the same claim.
+ */
+export declare const environmentReachabilitySchema: v.ObjectSchema<{
+    /** Addresses the provider states carry traffic for the URL's host, in ITS preference order. */
+    readonly candidates: v.ArraySchema<v.ObjectSchema<{
+        /** An IP literal. Never a name: a name would just be the lookup that already failed. */
+        readonly address: v.StringSchema<undefined>;
+        /** What this address IS, for the diagnostic. Never load-bearing. */
+        readonly label: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    }, undefined>, undefined>;
+    /** What proving found, or null when nothing has probed this environment yet. */
+    readonly proof: v.NullableSchema<v.ObjectSchema<{
+        readonly state: v.PicklistSchema<["reached", "not_reached", "inconclusive", "unproved"], undefined>;
+        /**
+         * The stated address that CARRIED, or null when the URL's own name carried (the ordinary case)
+         * and when nothing carried at all. Read `state` to tell those two apart.
+         *
+         * This is the field a container bridge is built from, which is why the proof publishes the
+         * candidate that carried rather than the first that resolved: a bridge built from an unproved
+         * address is recorded as successfully applied while the tester still fails, and the evidence
+         * then points further from the cause than no bridge at all did.
+         */
+        readonly via: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /**
+         * The {@link EnvironmentUnreachableReason} when `state` is `not_reached` or `inconclusive`,
+         * else null. An open string on the wire so a stored proof written by an older build never fails
+         * to parse; readers that branch on it treat an unknown value as "not one of the cases I handle".
+         */
+        readonly reason: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        /** Every target tried, in order. Recorded whether or not one carried. */
+        readonly attempts: v.ArraySchema<v.ObjectSchema<{
+            /** `host:port` for the name itself, `host@address:port` for a stated address. */
+            readonly target: v.StringSchema<undefined>;
+            /** `carried`, or the {@link EnvironmentUnreachableReason} that target produced. */
+            readonly outcome: v.StringSchema<undefined>;
+            /**
+             * What the probe said when it could not classify its own failure, capped for a rendered
+             * surface. The ONLY field carrying WHY a `probe_failed` attempt failed.
+             *
+             * Kept because `probe_failed` names no layer by design, so without this an operator reading a
+             * proof cannot tell a TLS or resolver fault from a runtime restriction from a bug in the probe:
+             * the three need different fixes and the reason renders identically for all of them. Absent for
+             * every other outcome, which is already self-describing.
+             */
+            readonly detail: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+        }, undefined>, undefined>;
+        /** When the proof ran (epoch ms). */
+        readonly checkedAt: v.NumberSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+export type EnvironmentReachability = v.InferOutput<typeof environmentReachabilitySchema>;
+/**
+ * The reachability facts an agent (or a container dispatch) is handed for ONE environment it is
+ * being pointed at.
+ *
+ * A flattened projection rather than the stored shape, because the reader's question is narrower
+ * than the operator's: it needs the address it may dial and the layer that failed, not the
+ * provider's full candidate list. `state: 'reached'` with no `address` means the name itself
+ * carried, which is the case that needs no narration at all.
+ */
+export interface EnvironmentReachabilityNote {
+    /**
+     * Deliberately NOT the proof's full state union: an `unproved` note is unrepresentable, because
+     * the projection withholds it (see {@link reachabilityNote}). A reader that branched on
+     * `'unproved'` here would be writing a case its input can never hold.
+     */
+    state: Exclude<EnvironmentRouteProof['state'], 'unproved'>;
+    /** The address that carried, when the name did not. */
+    address?: string;
+    reason?: string;
+    /** What a `probe_failed` attempt said, when one did. See the attempt's own `detail`. */
+    detail?: string;
+}
+/**
+ * Project a stored {@link EnvironmentReachability} onto the note an agent or a dispatch reads, or
+ * undefined when there is nothing to say.
+ *
+ * Undefined in two cases, and they are the same fact from two directions: no proof has been
+ * written, and a proof recording that nothing was WIRED to probe. "Nothing has looked" is the
+ * ordinary state of an environment mid-provision AND the permanent state of a deployment with no
+ * prober, so narrating it would put an unverified-reachability warning on every prompt of such a
+ * deployment and train a reader to skip the section that matters. The row still records the
+ * `unproved` proof, because when the probe ran is a fact an operator reads off the environment.
+ */
+export declare function reachabilityNote(reachability: EnvironmentReachability | null | undefined): EnvironmentReachabilityNote | undefined;
+/** Where an environment URL is dialled: its host, the port, and the scheme it names. */
+export interface EnvironmentCoordinates {
+    host: string;
+    /** Explicit from the URL, else the scheme default (443/80), else null: nothing to dial. */
+    port: number | null;
+    /** URL scheme without the trailing colon (e.g. `https`). */
+    scheme: string;
+}
+/**
+ * Derive the coordinates of an environment URL, or null when there is no URL or it does not parse.
+ *
+ * ONE deriver, here rather than beside either of its two readers, because they have to agree about
+ * the same string and the divergence is not cosmetic: the route proof DIALS what this returns and
+ * the Tester prompt states it to the agent as the environment's Host / Port / Scheme. Two parsers
+ * mean an agent told to dial coordinates the platform never probed, and the copies this replaced
+ * had already diverged on the one case that mattered (an unknown scheme became port `0` in one and
+ * `null` in the other, and `0` is what routed a non-http URL into a failed deploy).
+ *
+ * The parse is hand-rolled because contracts compiles against `lib: ["ES2022"]` with no DOM and no
+ * Node types, so `URL` is unavailable here exactly as it is in kernel, and this is the one package
+ * both readers can see. The three things a naive split gets wrong are handled: userinfo (whose
+ * password may itself contain `@`, so the LAST one separates it from the host), a bracketed IPv6
+ * literal (kept bracketed, which is what `URL.hostname` also returns), and an explicit port, where
+ * a MALFORMED one answers null rather than being dropped so a garbled URL cannot be silently
+ * dialled on the scheme default. Deliberately not attempted: IDNA/punycode and percent-decoding,
+ * neither of which an environment URL from a provider needs.
+ *
+ * An unknown scheme yields `port: null` (there is no default to invent), which every caller reads
+ * as "nothing to dial".
+ */
+export declare function deriveEnvironmentCoordinates(url: string | null | undefined): EnvironmentCoordinates | null;
+//# sourceMappingURL=environment-reachability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"environment-reachability.d.ts","sourceRoot":"","sources":["../src/environment-reachability.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,CAAC,MAAM,SAAS,CAAA;AAE5B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,wBAAwB;IACnC,wFAAwF;;IAExF,oEAAoE;;aAEpE,CAAA;AACF,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,wBAAwB,CAAC,CAAA;AAE/E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kCAAkC,uIAO7C,CAAA;AACF,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,kCAAkC,CAAC,CAAA;AAEnG,iFAAiF;AACjF,eAAO,MAAM,6BAA6B;IACxC,iFAAiF;;IAEjF,mFAAmF;;IAEnF;;;;;;;;OAQG;;aAEH,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B;;IAEtC;;;;;;;;OAQG;;IAEH;;;;OAIG;;IAEH,yEAAyE;;QAtDzE,iFAAiF;;QAEjF,mFAAmF;;QAEnF;;;;;;;;WAQG;;;IA4CH,qCAAqC;;aAErC,CAAA;AACF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,2BAA2B,CAAC,CAAA;AAErF;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B;IACxC,+FAA+F;;QAlH/F,wFAAwF;;QAExF,oEAAoE;;;IAkHpE,gFAAgF;;;QAnChF;;;;;;;;WAQG;;QAEH;;;;WAIG;;QAEH,yEAAyE;;YAtDzE,iFAAiF;;YAEjF,mFAAmF;;YAEnF;;;;;;;;eAQG;;;QA4CH,qCAAqC;;;aAmBrC,CAAA;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,WAAW,CAAC,OAAO,6BAA6B,CAAC,CAAA;AAEzF;;;;;;;;GAQG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAA;IAC1D,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GACvD,2BAA2B,GAAG,SAAS,CAUzC;AAED,wFAAwF;AACxF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,2FAA2F;IAC3F,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAA;CACf;AAKD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,sBAAsB,GAAG,IAAI,CAW/B"}

package/dist/environment-reachability.js

@@ -0,0 +1,248 @@
+// Whether a `ready` environment can actually be REACHED, as opposed to whether it was
+// provisioned.
+//
+// These are two questions, and the platform only ever asked the first one. An environment
+// carries one nullable `url`, so "reachable" has meant "a URL exists"; the tester is then handed
+// a name, gets `curl` exit code 000, and reports the one hypothesis its own task makes salient,
+// that the ENVIRONMENT is down. That reading is wrong often enough to be expensive: a name that
+// does not resolve, a route that does not carry, and an application that answers 503 are three
+// different faults with three different owners, and a connection failure renders all three
+// identically.
+//
+// The vocabulary here is the platform's answer to the LOWER two layers. It is deliberately a
+// SIBLING of `EnvironmentFailureReason` rather than an extension of it: that one is
+// provisioning-scoped in every member and in its docstring (`cluster_unreachable` means the
+// PROVIDER could not be reached), and a reaching failure against an environment the provider
+// calls `ready` is a different question for a different audience. Only the one-word verdict the
+// DEPLOYER settles on lives over there (`environment_unreachable`), because the deployer settles
+// in that vocabulary.
+import * as v from 'valibot';
+/**
+ * One address a provider states will carry traffic for its environment's URL host.
+ *
+ * The motivating shape is an org running per-PR preview environments whose per-environment DNS
+ * record lives in an internal view while the load balancers fronting it are ordinary names and
+ * the ingress routes on the `Host` header. The address exists and a container's egress reaches
+ * it. The only missing thing is a name-to-address mapping, which is exactly what a hosts-file
+ * entry (or a Kubernetes `hostAliases` entry) is.
+ *
+ * `label` is for the human reading a diagnostic ("internal ALB", "public ALB"), never for
+ * matching: the platform picks by PROBING, never by name.
+ */
+export const environmentAddressSchema = v.object({
+    /** An IP literal. Never a name: a name would just be the lookup that already failed. */
+    address: v.string(),
+    /** What this address IS, for the diagnostic. Never load-bearing. */
+    label: v.optional(v.string()),
+});
+/**
+ * Why a `ready` environment could not be reached, at the layer the platform can observe.
+ *
+ * Separate members rather than one "unreachable" because they need different reactions and name
+ * different owners: `name_unresolved` with candidates that also failed is an environment nobody
+ * can reach, `no_candidate` is a PROVIDER that never told us where the thing lives, and
+ * `connection_refused` is a route that carries to a box with nothing listening, which is the
+ * deployed workload rather than the network.
+ *
+ *  - `no_candidate`       the environment carries no URL, or one with no host to probe. There
+ *                         was nothing to try, which is not the same as trying and failing.
+ *  - `name_unresolved`    the URL's host resolved nowhere, and no stated address carried either.
+ *  - `no_route`           something resolved and the connect never completed (timeout,
+ *                         host/network unreachable). The expensive failure: a lookup that
+ *                         worked followed by a connect that hangs.
+ *  - `connection_refused` the route carries and nothing is listening on the port.
+ *  - `address_refused`    the provider stated an address the platform will not dial: loopback,
+ *                         link-local/vendor metadata, or a non-canonical literal. Recorded as an
+ *                         attempt rather than dropped, because a refused input is an omission the
+ *                         operator has to be able to see.
+ *  - `probe_failed`       the probe itself errored in a way it could not classify. Kept apart
+ *                         from the three above so "we could not tell" never renders as a
+ *                         verdict about the environment.
+ */
+export const environmentUnreachableReasonSchema = v.picklist([
+    'no_candidate',
+    'name_unresolved',
+    'no_route',
+    'connection_refused',
+    'address_refused',
+    'probe_failed',
+]);
+/** One target the proof tried, in the order it was tried, and what came back. */
+export const environmentRouteAttemptSchema = v.object({
+    /** `host:port` for the name itself, `host@address:port` for a stated address. */
+    target: v.string(),
+    /** `carried`, or the {@link EnvironmentUnreachableReason} that target produced. */
+    outcome: v.string(),
+    /**
+     * What the probe said when it could not classify its own failure, capped for a rendered
+     * surface. The ONLY field carrying WHY a `probe_failed` attempt failed.
+     *
+     * Kept because `probe_failed` names no layer by design, so without this an operator reading a
+     * proof cannot tell a TLS or resolver fault from a runtime restriction from a bug in the probe:
+     * the three need different fixes and the reason renders identically for all of them. Absent for
+     * every other outcome, which is already self-describing.
+     */
+    detail: v.optional(v.string()),
+});
+/**
+ * What the platform PROVED about reaching an environment, once, at the moment it went `ready`.
+ *
+ * `state` splits along TWO axes and both are load-bearing. `reached` and `not_reached` are
+ * verdicts about the ENVIRONMENT, and only `not_reached` fails a deployer frame. `inconclusive`
+ * and `unproved` are verdicts about the PLATFORM, and neither may ever fail anything: collapsing
+ * either into `not_reached` turns a diagnostic into a second way for a healthy deploy to die,
+ * which is the one failure mode this whole module must not introduce, and collapsing either into
+ * `reached` hands a tester the unbacked claim it exists to retire.
+ *
+ *   - `inconclusive` the platform LOOKED and established nothing either way: a probe that
+ *                    errored in a way it could not classify, or an environment with no address to
+ *                    dial. Narrated, because "we could not tell" is exactly the fact that stops an
+ *                    agent concluding the environment is dead.
+ *   - `unproved`     nothing was wired to open a socket, so nothing was tried. SILENT (see
+ *                    {@link reachabilityNote}): it is the standing state of every deployment with
+ *                    no prober, and a line on every prompt is a line nobody reads on the one
+ *                    prompt where it matters.
+ */
+export const environmentRouteProofSchema = v.object({
+    state: v.picklist(['reached', 'not_reached', 'inconclusive', 'unproved']),
+    /**
+     * The stated address that CARRIED, or null when the URL's own name carried (the ordinary case)
+     * and when nothing carried at all. Read `state` to tell those two apart.
+     *
+     * This is the field a container bridge is built from, which is why the proof publishes the
+     * candidate that carried rather than the first that resolved: a bridge built from an unproved
+     * address is recorded as successfully applied while the tester still fails, and the evidence
+     * then points further from the cause than no bridge at all did.
+     */
+    via: v.nullable(v.string()),
+    /**
+     * The {@link EnvironmentUnreachableReason} when `state` is `not_reached` or `inconclusive`,
+     * else null. An open string on the wire so a stored proof written by an older build never fails
+     * to parse; readers that branch on it treat an unknown value as "not one of the cases I handle".
+     */
+    reason: v.nullable(v.string()),
+    /** Every target tried, in order. Recorded whether or not one carried. */
+    attempts: v.array(environmentRouteAttemptSchema),
+    /** When the proof ran (epoch ms). */
+    checkedAt: v.number(),
+});
+/**
+ * Everything the platform knows about ADDRESSING an environment, beside the one string it knows
+ * about naming it.
+ *
+ * Two halves because they come from two places and one of them is a claim: `candidates` is what
+ * the PROVIDER said, `proof` is what the platform TRIED. Keeping the claim after the proof runs
+ * is deliberate: an operator debugging a dead environment wants to see which addresses were
+ * offered as well as which were reached, and a re-probe on a later poll re-reads the same claim.
+ */
+export const environmentReachabilitySchema = v.object({
+    /** Addresses the provider states carry traffic for the URL's host, in ITS preference order. */
+    candidates: v.array(environmentAddressSchema),
+    /** What proving found, or null when nothing has probed this environment yet. */
+    proof: v.nullable(environmentRouteProofSchema),
+});
+/**
+ * Project a stored {@link EnvironmentReachability} onto the note an agent or a dispatch reads, or
+ * undefined when there is nothing to say.
+ *
+ * Undefined in two cases, and they are the same fact from two directions: no proof has been
+ * written, and a proof recording that nothing was WIRED to probe. "Nothing has looked" is the
+ * ordinary state of an environment mid-provision AND the permanent state of a deployment with no
+ * prober, so narrating it would put an unverified-reachability warning on every prompt of such a
+ * deployment and train a reader to skip the section that matters. The row still records the
+ * `unproved` proof, because when the probe ran is a fact an operator reads off the environment.
+ */
+export function reachabilityNote(reachability) {
+    const proof = reachability?.proof;
+    if (!proof || proof.state === 'unproved')
+        return undefined;
+    const detail = proof.attempts.find((attempt) => attempt.detail)?.detail;
+    return {
+        state: proof.state,
+        ...(proof.via ? { address: proof.via } : {}),
+        ...(proof.reason ? { reason: proof.reason } : {}),
+        ...(detail ? { detail } : {}),
+    };
+}
+/** `scheme://` plus everything up to the path, query or fragment: the authority. */
+const URL_AUTHORITY = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
+/**
+ * Derive the coordinates of an environment URL, or null when there is no URL or it does not parse.
+ *
+ * ONE deriver, here rather than beside either of its two readers, because they have to agree about
+ * the same string and the divergence is not cosmetic: the route proof DIALS what this returns and
+ * the Tester prompt states it to the agent as the environment's Host / Port / Scheme. Two parsers
+ * mean an agent told to dial coordinates the platform never probed, and the copies this replaced
+ * had already diverged on the one case that mattered (an unknown scheme became port `0` in one and
+ * `null` in the other, and `0` is what routed a non-http URL into a failed deploy).
+ *
+ * The parse is hand-rolled because contracts compiles against `lib: ["ES2022"]` with no DOM and no
+ * Node types, so `URL` is unavailable here exactly as it is in kernel, and this is the one package
+ * both readers can see. The three things a naive split gets wrong are handled: userinfo (whose
+ * password may itself contain `@`, so the LAST one separates it from the host), a bracketed IPv6
+ * literal (kept bracketed, which is what `URL.hostname` also returns), and an explicit port, where
+ * a MALFORMED one answers null rather than being dropped so a garbled URL cannot be silently
+ * dialled on the scheme default. Deliberately not attempted: IDNA/punycode and percent-decoding,
+ * neither of which an environment URL from a provider needs.
+ *
+ * An unknown scheme yields `port: null` (there is no default to invent), which every caller reads
+ * as "nothing to dial".
+ */
+export function deriveEnvironmentCoordinates(url) {
+    if (!url)
+        return null;
+    const match = URL_AUTHORITY.exec(url.trim());
+    if (!match)
+        return null;
+    const scheme = (match[1] ?? '').toLowerCase();
+    const authority = match[2] ?? '';
+    const hostPort = authority.slice(authority.lastIndexOf('@') + 1);
+    const split = splitHostPort(hostPort);
+    if (!split)
+        return null;
+    const port = split.port ?? defaultPortForScheme(scheme);
+    return { host: split.host, port, scheme };
+}
+/** The default port a scheme implies, or null when it implies none the platform knows. */
+function defaultPortForScheme(scheme) {
+    return scheme === 'https' ? 443 : scheme === 'http' ? 80 : null;
+}
+/**
+ * Split an authority's `host[:port]` half, or null when it is not one.
+ *
+ * Null rather than a best guess for every malformed shape: an unclosed bracket, an unbracketed
+ * literal carrying several colons (an IPv6 address that a URL may not spell that way), and a port
+ * that is not a number in range. Each of those is a URL `new URL` would throw on, and answering
+ * with a host anyway is how a garbled URL gets dialled.
+ */
+function splitHostPort(hostPort) {
+    if (hostPort.startsWith('[')) {
+        const close = hostPort.indexOf(']');
+        if (close < 1)
+            return null;
+        const host = hostPort.slice(0, close + 1).toLowerCase();
+        const rest = hostPort.slice(close + 1);
+        if (rest === '')
+            return { host, port: null };
+        if (!rest.startsWith(':'))
+            return null;
+        const port = parsePort(rest.slice(1));
+        return port === null ? null : { host, port };
+    }
+    const colon = hostPort.indexOf(':');
+    if (colon < 0)
+        return hostPort ? { host: hostPort.toLowerCase(), port: null } : null;
+    if (hostPort.indexOf(':', colon + 1) >= 0)
+        return null;
+    const host = hostPort.slice(0, colon).toLowerCase();
+    const port = parsePort(hostPort.slice(colon + 1));
+    return host && port !== null ? { host, port } : null;
+}
+/** A port as written in a URL: digits, 1-65535. Null for anything else. */
+function parsePort(raw) {
+    if (!/^\d{1,5}$/.test(raw))
+        return null;
+    const port = Number(raw);
+    return port >= 1 && port <= 65535 ? port : null;
+}
+//# sourceMappingURL=environment-reachability.js.map

package/dist/environment-reachability.js.map

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