@cat-factory/contracts 0.335.0 → 0.337.0

package/dist/environment-investigation.js

@@ -0,0 +1,258 @@
+import * as v from 'valibot';
+// ---------------------------------------------------------------------------
+// ENVIRONMENT INVESTIGATION: the vocabulary of what the platform does when an environment never
+// becomes usable and no checkout edit can help.
+//
+// The sibling of `deploy-fix.ts`, and deliberately its opposite half. The `deploy-fixer` runs
+// only for `manifest_invalid`: a document the checkout owns and got wrong. Everything else a
+// provisioning failure can be (a VM that went offline under a deploy job that reported success, a
+// load balancer with no healthy target, a DNS record that was never published) lives entirely in
+// the provider, and the conclusion the platform drew from "a code fixer cannot help here" used to
+// be "nobody can help here": the run died at the tester with a report correctly saying a human had
+// to look. What actually follows is that a DIFFERENT investigator is needed, one whose evidence is
+// the provider rather than the repository.
+//
+// The division of labour is the one CLAUDE.md states for every model-in-the-loop decision: the
+// model JUDGES (which layer is at fault, on which evidence) and the platform COMPUTES (which
+// action it is allowed to take, whether it takes it, and, always, whether the environment came
+// up afterwards). The verdict is never the proof. The re-probe is.
+//
+// Tracker: `docs/initiatives/environment-investigation.md`.
+// ---------------------------------------------------------------------------
+// Every schema below that ends up INSIDE a pipeline step is declared as an explicit interface and
+// annotated `v.GenericSchema<unknown, T>` rather than inferred with `v.InferOutput`, the shape
+// `binaryGenerationOptionsSchema` already uses. The investigation state nests four object levels
+// under `PipelineStep` (step → state → attempt → verdict → evidence), which is deep enough that
+// inferring it tips `tsc` into "type instantiation is excessively deep" in a consumer several
+// packages away. It was first seen in `WorkspaceService`, which is nowhere near this file and gives a
+// reader nothing to go on. `unknown` on the input side is what a parser accepts anyway.
+/** The inline engine kind the investigation runs under (model resolution + spend attribution). */
+export const ENVIRONMENT_INVESTIGATOR_AGENT_KIND = 'environment-investigator';
+/**
+ * WHERE the fault the investigator found lives, which is the one thing its report has to settle:
+ * every reader (the run's recorded failure, an operator, a later retry) does something different
+ * per layer, and today they all get the same "the environment did not come up".
+ *
+ *  - `provider`: the infrastructure the platform asked for is broken or was never delivered. A
+ *    VM that went offline, a balancer with no healthy target, a DNS record never published, a
+ *    quota refusal. The platform can sometimes retry into it and can never fix it.
+ *  - `platform`: cat-factory itself got it wrong. A readiness ceiling that expired on an
+ *    environment still legitimately converging, a URL published before it resolved, a poll that
+ *    read a field the provider does not populate.
+ *  - `deployment`: the description the run deployed is at fault, but NOT in a way the
+ *    `manifest_invalid` classifier caught (a workload that starts and crashes, an image the
+ *    cluster cannot pull). Distinct from `provider` because the fix is a commit; distinct from the
+ *    deploy-fixer's admission because the finding is a HYPOTHESIS and does not itself dispatch a
+ *    container against a checkout.
+ *  - `unknown`: the evidence did not settle it. A first-class answer, never a default dressed up
+ *    as one: "we could not tell" and "the provider is broken" send different people to different
+ *    places, and collapsing them is how an operator ends up debugging a healthy cluster.
+ */
+export const environmentFaultLayerSchema = v.picklist([
+    'provider',
+    'platform',
+    'deployment',
+    'unknown',
+]);
+/**
+ * What the platform may DO about it, as a closed vocabulary the model picks from and the engine
+ * executes. The model never acts: it names one of these and the engine decides whether this
+ * deployment, this provider and this budget allow it.
+ *
+ *  - `stop`: nothing here is retryable. The run fails with the investigator's named cause instead
+ *    of a tester's guess, which is the whole point of the second outcome.
+ *  - `wait`: the environment is converging and the ceiling was simply too tight for it. Extends
+ *    the readiness wait ONCE, by the ceiling again.
+ *  - `restart`: restart the workload in place, without rebuilding anything around it. The one
+ *    action that needs the provider to implement `EnvironmentDiagnostics.remediate`.
+ *  - `reprovision`: stand it up again over the same target. Idempotent for every provider whose
+ *    provision is an apply; the existing environment is left in place.
+ *  - `recreate`: tear the environment down first, then stand it up again. For a target whose own
+ *    state is what is wrong, where re-applying over it would reproduce the fault.
+ */
+export const environmentRemediationActionSchema = v.picklist([
+    'stop',
+    'wait',
+    'restart',
+    'reprovision',
+    'recreate',
+]);
+/**
+ * Whether an action needs the provider to implement the optional remediation capability.
+ *
+ * An exhaustive `Record` rather than a membership test, for the reason
+ * `REPO_FIXABLE_ENVIRONMENT_FAILURES` is one: the default a new action would silently inherit is
+ * wrong in both directions. `false` on an action no provider can perform makes the engine promise
+ * something and do nothing; `true` on one the platform owns outright (tearing an environment down
+ * and standing it up again are `EnvironmentProvider` methods every provider already has) withholds
+ * the only remedy available from every provider that never implemented diagnostics.
+ */
+const REMEDIATION_NEEDS_PROVIDER_SUPPORT = {
+    stop: false,
+    wait: false,
+    restart: true,
+    reprovision: false,
+    recreate: false,
+};
+/** See {@link REMEDIATION_NEEDS_PROVIDER_SUPPORT}. */
+export function remediationNeedsProviderSupport(action) {
+    return REMEDIATION_NEEDS_PROVIDER_SUPPORT[action];
+}
+/**
+ * Narrow an arbitrary string to a member, DERIVED from the picklist's own options so adding one
+ * needs no second edit here. Used wherever a PERSISTED action is read back: the vocabulary is
+ * closed and stored on a run's step, so a member retired later is still in the database, and a
+ * reader that assumed the type was total would splice `undefined` into the very message whose job
+ * is to name what a human must re-pick (CLAUDE.md's closed-vocabulary rule).
+ */
+export function isEnvironmentRemediationAction(value) {
+    if (!value)
+        return false;
+    return environmentRemediationActionSchema.options.includes(value);
+}
+/** Compile-time totality guard for {@link describeRemediationAction}. */
+function unrecognisedRemediation(action) {
+    return `an unrecognised remediation (${JSON.stringify(action)})`;
+}
+/**
+ * One-line description of a stored action, for an operator-facing message. Total against the TYPE
+ * through the `never` helper (adding a member fails the build) and honest about the DATA: a value
+ * that is no longer a member is named as retired rather than guessed onto a current one, because
+ * nothing knows which one was meant.
+ */
+export function describeRemediationAction(action) {
+    if (!isEnvironmentRemediationAction(action)) {
+        return `a remediation this deployment no longer offers (${JSON.stringify(action)})`;
+    }
+    switch (action) {
+        case 'stop':
+            return 'stop and report the cause';
+        case 'wait':
+            return 'keep waiting for the environment to converge';
+        case 'restart':
+            return 'restart the workload in place';
+        case 'reprovision':
+            return 'provision the environment again';
+        case 'recreate':
+            return 'tear the environment down and provision it again';
+        default:
+            return unrecognisedRemediation(action);
+    }
+}
+export const environmentEvidenceItemSchema = v.object({
+    source: v.pipe(v.string(), v.maxLength(120)),
+    statement: v.pipe(v.string(), v.maxLength(1000)),
+});
+export const environmentInvestigationVerdictSchema = v.object({
+    faultLayer: environmentFaultLayerSchema,
+    summary: v.pipe(v.string(), v.maxLength(4000)),
+    evidence: v.array(environmentEvidenceItemSchema),
+    action: environmentRemediationActionSchema,
+    actionRationale: v.pipe(v.string(), v.maxLength(1000)),
+});
+/** At most this many cited facts survive coercion; past it the model is padding, not evidencing. */
+const MAX_EVIDENCE_ITEMS = 20;
+function isFaultLayer(value) {
+    return (typeof value === 'string' &&
+        environmentFaultLayerSchema.options.includes(value));
+}
+/**
+ * Trim a prose field to `max` characters INCLUSIVE of the ellipsis that states the drop.
+ *
+ * The ellipsis counts against the budget rather than riding on top of it, because `max` is the
+ * same number the schema beside it declares as `v.maxLength`: a coercion that answered `max + 1`
+ * produced a value its own validator then rejected, on a field persisted to `step
+ * .environmentInvestigation` and served through `executionInstanceSchema`, whose lengths are
+ * published into the OpenAPI spec and the four SDKs.
+ */
+function coerceText(value, max) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max - 1)}…`;
+}
+function coerceEvidence(value) {
+    if (!Array.isArray(value))
+        return [];
+    const items = [];
+    for (const entry of value) {
+        if (items.length >= MAX_EVIDENCE_ITEMS)
+            break;
+        if (!entry || typeof entry !== 'object')
+            continue;
+        const record = entry;
+        const statement = coerceText(record.statement, 1000);
+        if (!statement)
+            continue;
+        items.push({ source: coerceText(record.source, 120) ?? 'unattributed', statement });
+    }
+    return items;
+}
+/**
+ * Read a model reply into a verdict, LENIENTLY in the fields that are prose and STRICTLY in the
+ * two that are decisions.
+ *
+ * A fault layer or an action the model invented is not coerced onto a neighbour: both drop to the
+ * value meaning "this did not settle anything" (`unknown` / `stop`), because the action is the one
+ * field where a generous reading spends real infrastructure on a guess. The prose fields degrade
+ * field-by-field instead of discarding the whole verdict, since a report whose `evidence` array is
+ * malformed still names a cause worth putting on the record.
+ *
+ * Returns null when there is no object at all. The caller then records the investigation as FAILED,
+ * which is not the same as a verdict of `stop` and must never read like one.
+ */
+export function coerceEnvironmentInvestigationVerdict(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const value = raw;
+    const action = typeof value.action === 'string' ? value.action : undefined;
+    return {
+        faultLayer: isFaultLayer(value.faultLayer) ? value.faultLayer : 'unknown',
+        summary: coerceText(value.summary, 4000) ?? '',
+        evidence: coerceEvidence(value.evidence),
+        action: isEnvironmentRemediationAction(action) ? action : 'stop',
+        actionRationale: coerceText(value.actionRationale, 1000) ?? '',
+    };
+}
+/**
+ * How many investigation rounds a `deployer` step gets. Two, for the reason the deploy-fixer's
+ * budget is two: the first round has the whole evidence bag and the provider's own account, and a
+ * second covers a remedy that was right about the layer and wrong about the action. A third round
+ * against an environment that has twice refused to come up is not converging, and each round costs
+ * an LLM call plus real infrastructure work.
+ */
+export const DEFAULT_ENVIRONMENT_INVESTIGATION_MAX_ATTEMPTS = 2;
+/** Bounds on the per-step budget: `0` disables the loop, 5 is the ceiling. */
+export const environmentInvestigationAttemptsSchema = v.pipe(v.number(), v.integer(), v.minValue(0), v.maxValue(5));
+export const environmentInvestigationConfigSchema = v.object({
+    enabled: v.optional(v.boolean()),
+    maxAttempts: v.optional(environmentInvestigationAttemptsSchema),
+    allowRemediation: v.optional(v.boolean()),
+});
+export const environmentInvestigationAttemptSchema = v.object({
+    attempt: v.number(),
+    at: v.number(),
+    outcome: v.picklist(['reported', 'remediated', 'failed']),
+    reason: v.optional(v.nullable(v.string())),
+    error: v.string(),
+    verdict: v.optional(v.nullable(environmentInvestigationVerdictSchema)),
+    ranAction: v.optional(v.nullable(v.string())),
+    withheld: v.optional(v.nullable(v.string())),
+    failure: v.optional(v.nullable(v.string())),
+});
+/**
+ * How many readiness-ceiling extensions a `wait` verdict may win, across the whole step. One: a
+ * second would let a model postpone a run indefinitely, one ceiling at a time.
+ */
+export const MAX_ENVIRONMENT_WAIT_EXTENSIONS = 1;
+export const environmentInvestigationStateSchema = v.object({
+    attempts: v.number(),
+    maxAttempts: v.number(),
+    frameId: v.string(),
+    environmentId: v.optional(v.nullable(v.string())),
+    waitExtensions: v.optional(v.nullable(v.number())),
+    attemptLog: v.optional(v.nullable(v.array(environmentInvestigationAttemptSchema))),
+});
+//# sourceMappingURL=environment-investigation.js.map

package/dist/environment-investigation.js.map

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

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"}