@vincentt-xr/cli 0.15.1 → 0.16.0

package/dist/domain/hostname.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The registrable domains the platform owns (how-it-works.md § The
+ * platform-hostname refusal).
+ *
+ * EXACT MATCH, or SUFFIX WITH A LEADING DOT. The leading dot is the label
+ * boundary; its absence is the `evilvincentt.app` bug — that name is a DIFFERENT
+ * registrable domain and is correctly ACCEPTED.
+ *
+ * This list is duplicated from the Go implementation deliberately and it is safe
+ * to duplicate for the reason the record gives: it changes only when the company
+ * buys a domain, an event with a purchase order attached. The server checks it
+ * too, and the server's answer is the one that decides — this copy exists so the
+ * refusal costs no round trip, not so the CLI can be the authority.
+ */
+export declare const PLATFORM_REGISTRABLE_DOMAINS: readonly ["vincentt.app", "vincentt.dev", "vincentt.studio"];
+/**
+ * Shape the creator's argument for the path segment.
+ *
+ * Lowercase, trim surrounding whitespace, strip a trailing dot, and strip a
+ * scheme and any path a creator pasted from a browser bar. The trailing-dot strip
+ * PRECEDES the port truncation, matching the server spec's load-bearing ordering
+ * — without that order the composed case `host.example.com.:8443` normalizes
+ * wrong.
+ *
+ * Anything else — a name with an invalid character, an over-long label, a
+ * punycode label — is passed THROUGH to the server unchanged, which refuses it
+ * with the copy it owns. A client-side reject for those would be a second spec.
+ */
+export declare function normalizeArgument(input: string): string;
+/**
+ * Is this a hostname under a registrable domain the platform owns?
+ *
+ * Exact match or leading-dot suffix. Case-folded because the caller may not have
+ * normalized yet.
+ */
+export declare function isPlatformHostname(host: string): boolean;
+/**
+ * Does this name have no subdomain — i.e. is it a root domain?
+ *
+ * Two labels or fewer. This is a LABEL COUNT, not a public-suffix computation,
+ * and the difference matters in one direction only: `acme.co.uk` is a root domain
+ * that this returns false for, so the CLI sends it and the SERVER refuses it with
+ * the same copy. That is the correct failure direction — a client-side check that
+ * guessed at public suffixes would refuse `ar.acme.co.uk`, a name f16 accepts.
+ */
+export declare function isRootDomain(host: string): boolean;
+/** A local refusal, decided with no network call. */
+export type LocalRefusal = "platform_host" | "root_domain" | "empty";
+/**
+ * The local refusal for this argument, or undefined to send it on.
+ *
+ * ORDER MATTERS: the platform check runs FIRST. `vincentt.app` is both a
+ * two-label root domain and a platform address, and "that's already a Vincentt
+ * address" is the true and useful answer while "root domains aren't supported"
+ * would send the creator to try `thing.vincentt.app`, which is also refused.
+ */
+export declare function localRefusal(input: string): LocalRefusal | undefined;

package/dist/domain/hostname.js

@@ -0,0 +1,116 @@
+// Client-side hostname handling for `vincentt domain <verb> <hostname>`.
+//
+// THE SERVER IS AUTHORITATIVE. The API normalizes the hostname by its own
+// 12-step ordered specification and refuses what it will not accept, and the
+// routes are hostname-keyed with the path segment normalized before any store
+// read. Everything here is a LOCAL CONVENIENCE with two jobs and no third:
+//
+//   1. Put the argument into the shape the path segment expects, so a creator
+//      typing `AR.Acme.COM.` reaches the same row as `ar.acme.com`.
+//   2. Refuse, with no network call, the two cases whose copy is a fact about the
+//      creator's own registrar rather than about our state: a root domain and a
+//      platform address.
+//
+// It deliberately does NOT reimplement the server's 12 steps. A second
+// implementation of a normalization spec is a second thing that can drift, and
+// the record names exactly three implementations of that spec (Go, the edge
+// Function, the meter's reducer) with a shared fixture pinning them. Adding a
+// fourth in the CLI, unpinned by that fixture, is how the CLI comes to accept a
+// name the API rejects — or worse, to rewrite one into a different valid name.
+//
+// WHAT THE CLI DISPLAYS IS ALWAYS WHAT THE API RETURNED. `normalizeArgument` only
+// shapes the value we SEND; once a response is in hand, every rendered hostname
+// comes from `domain` on the wire.
+/**
+ * The registrable domains the platform owns (how-it-works.md § The
+ * platform-hostname refusal).
+ *
+ * EXACT MATCH, or SUFFIX WITH A LEADING DOT. The leading dot is the label
+ * boundary; its absence is the `evilvincentt.app` bug — that name is a DIFFERENT
+ * registrable domain and is correctly ACCEPTED.
+ *
+ * This list is duplicated from the Go implementation deliberately and it is safe
+ * to duplicate for the reason the record gives: it changes only when the company
+ * buys a domain, an event with a purchase order attached. The server checks it
+ * too, and the server's answer is the one that decides — this copy exists so the
+ * refusal costs no round trip, not so the CLI can be the authority.
+ */
+export const PLATFORM_REGISTRABLE_DOMAINS = [
+    "vincentt.app",
+    "vincentt.dev",
+    "vincentt.studio",
+];
+/**
+ * Shape the creator's argument for the path segment.
+ *
+ * Lowercase, trim surrounding whitespace, strip a trailing dot, and strip a
+ * scheme and any path a creator pasted from a browser bar. The trailing-dot strip
+ * PRECEDES the port truncation, matching the server spec's load-bearing ordering
+ * — without that order the composed case `host.example.com.:8443` normalizes
+ * wrong.
+ *
+ * Anything else — a name with an invalid character, an over-long label, a
+ * punycode label — is passed THROUGH to the server unchanged, which refuses it
+ * with the copy it owns. A client-side reject for those would be a second spec.
+ */
+export function normalizeArgument(input) {
+    let s = input.trim().toLowerCase();
+    // A creator or an agent pasting from a browser hands over a URL. Taking the
+    // host out of it is unambiguous; guessing at anything else is not.
+    s = s.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    const slash = s.indexOf("/");
+    if (slash !== -1)
+        s = s.slice(0, slash);
+    // Trailing dot BEFORE the colon, per the spec's ordering.
+    if (s.endsWith("."))
+        s = s.slice(0, -1);
+    const colon = s.lastIndexOf(":");
+    if (colon !== -1)
+        s = s.slice(0, colon);
+    if (s.endsWith("."))
+        s = s.slice(0, -1);
+    return s;
+}
+/**
+ * Is this a hostname under a registrable domain the platform owns?
+ *
+ * Exact match or leading-dot suffix. Case-folded because the caller may not have
+ * normalized yet.
+ */
+export function isPlatformHostname(host) {
+    const h = normalizeArgument(host);
+    return PLATFORM_REGISTRABLE_DOMAINS.some((d) => h === d || h.endsWith(`.${d}`));
+}
+/**
+ * Does this name have no subdomain — i.e. is it a root domain?
+ *
+ * Two labels or fewer. This is a LABEL COUNT, not a public-suffix computation,
+ * and the difference matters in one direction only: `acme.co.uk` is a root domain
+ * that this returns false for, so the CLI sends it and the SERVER refuses it with
+ * the same copy. That is the correct failure direction — a client-side check that
+ * guessed at public suffixes would refuse `ar.acme.co.uk`, a name f16 accepts.
+ */
+export function isRootDomain(host) {
+    const h = normalizeArgument(host);
+    if (!h)
+        return false;
+    return h.split(".").filter((l) => l.length > 0).length <= 2;
+}
+/**
+ * The local refusal for this argument, or undefined to send it on.
+ *
+ * ORDER MATTERS: the platform check runs FIRST. `vincentt.app` is both a
+ * two-label root domain and a platform address, and "that's already a Vincentt
+ * address" is the true and useful answer while "root domains aren't supported"
+ * would send the creator to try `thing.vincentt.app`, which is also refused.
+ */
+export function localRefusal(input) {
+    const h = normalizeArgument(input);
+    if (!h)
+        return "empty";
+    if (isPlatformHostname(h))
+        return "platform_host";
+    if (isRootDomain(h))
+        return "root_domain";
+    return undefined;
+}

package/dist/domain/names.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The two forms of one record name, labelled by the OBSERVABLE TELL rather than
+ * by the DNS concept.
+ *
+ * `relative` may be undefined: see `relativeName`. When it is, only the FQDN
+ * prints, because inventing a relative form we cannot derive is exactly the
+ * wrong-form paste this whole module exists to prevent.
+ */
+export interface NamePair {
+    /** The short form. Printed FIRST — the majority want it, and the first line is what a hurrying creator copies. */
+    relative?: string;
+    /** The fully-qualified name, exactly as the API sent it. */
+    fqdn: string;
+}
+/**
+ * The relative form of `fqdn` within `zone`, or undefined when it cannot be
+ * derived.
+ *
+ * Undefined in three cases, and each is a deliberate refusal rather than a gap:
+ *
+ *   1. `fqdn` is not inside `zone`. Deriving a relative name against the wrong
+ *      zone produces a plausible string that creates the wrong record.
+ *   2. `fqdn` IS the zone. The relative form is the registrar's own apex
+ *      convention (`@`, blank, or the zone name depending on vendor), and there
+ *      is no single value that is right everywhere. f16 refuses root domains at
+ *      attach anyway, so this arm is unreachable from the attach path — it is
+ *      here because a caller could reach it from a record on a zone-level CAA.
+ *   3. The zone is empty or the fqdn is empty.
+ *
+ * The comparison is CASE-INSENSITIVE on the suffix but the returned value is a
+ * slice of the ORIGINAL `fqdn`, so a mixed-case name the API sent renders in the
+ * case the API sent it. The API always sends the normalized lowercase form; the
+ * slice-not-lowercase choice means this function cannot itself introduce a
+ * discrepancy between what we display and what we were given.
+ */
+export declare function relativeName(fqdn: string, zone: string): string | undefined;
+/**
+ * The pair for one record name, given the domain being attached.
+ *
+ * `zone` is the ATTACHED DOMAIN (`ar.acme.com`), not the registrable domain
+ * (`acme.com`), and that is the correct choice for the reason the transcripts
+ * show: the creator is editing DNS for `acme.com`, so the relative name of
+ * `_vincentt-challenge.ar.acme.com` is `_vincentt-challenge.ar`.
+ *
+ * That means the zone passed here is the REGISTRABLE domain in practice, and the
+ * caller decides which — `recordNamePairs` takes it explicitly rather than
+ * guessing, because a guess at the registrable domain requires a public-suffix
+ * list the CLI deliberately does not ship (`ar.acme.co.uk` would break a
+ * two-label heuristic).
+ */
+export declare function namePair(fqdn: string, zone: string): NamePair;
+/**
+ * The zone a relative name is relative TO, derived from the attached domain by
+ * dropping its first label.
+ *
+ * `ar.acme.com` → `acme.com`. This is NOT a public-suffix computation and does
+ * not claim to be one: it answers "what will the registrar's form append", and
+ * the registrar whose form appends anything is administering the zone the
+ * attached name sits directly inside. For `ar.acme.co.uk` this yields
+ * `acme.co.uk`, which is the correct zone for that record, while a
+ * public-suffix-based "registrable domain" would also yield `acme.co.uk`. The
+ * two agree wherever the attached name is one label below its zone, which is
+ * every name f16 accepts (root domains are refused at attach).
+ *
+ * Returns undefined for a single-label input, which attach refuses anyway.
+ */
+export declare function zoneOf(domain: string): string | undefined;
+/**
+ * Every record's name pair, in the order the API sent the records.
+ *
+ * The order is the API's and is never re-sorted here: the transcripts put the
+ * pointer CNAME first, the ownership TXT second and the certificate validation
+ * CNAME third, and that order is the API's to choose. A client that sorted would
+ * put the keep-this-one caption on whichever record happened to land third.
+ */
+export declare function recordNamePairs(records: readonly {
+    name: string;
+}[], domain: string): NamePair[];

package/dist/domain/names.js

@@ -0,0 +1,113 @@
+// The two-form name problem — "the single most likely real-world failure in the
+// feature" (implementation.md § The contract trap) and "the most expensive copy
+// decision" (how-it-works.md Flow C1).
+//
+// The API emits `records[].name` as the FULLY-QUALIFIED name. Roughly half of
+// registrar UIs append the zone themselves and expect the RELATIVE name. Pasting
+// the wrong form produces a record that never verifies, and the ticket reads as
+// our bug.
+//
+// This module derives the relative form. It is the ONE derivation the CLI performs
+// on a record, and it is a SUBTRACTION from the value the API sent rather than an
+// assembly from parts — which is what keeps "records are printed verbatim" true.
+// The FQDN is always carried through untouched.
+/**
+ * Strip a trailing dot for comparison only. The API's own normalization already
+ * removes it, but a record name is a string a registrar or a future API version
+ * may hand back rooted, and a comparison that failed on the dot would silently
+ * drop the relative form on every record.
+ */
+function unroot(host) {
+    return host.endsWith(".") ? host.slice(0, -1) : host;
+}
+/**
+ * The relative form of `fqdn` within `zone`, or undefined when it cannot be
+ * derived.
+ *
+ * Undefined in three cases, and each is a deliberate refusal rather than a gap:
+ *
+ *   1. `fqdn` is not inside `zone`. Deriving a relative name against the wrong
+ *      zone produces a plausible string that creates the wrong record.
+ *   2. `fqdn` IS the zone. The relative form is the registrar's own apex
+ *      convention (`@`, blank, or the zone name depending on vendor), and there
+ *      is no single value that is right everywhere. f16 refuses root domains at
+ *      attach anyway, so this arm is unreachable from the attach path — it is
+ *      here because a caller could reach it from a record on a zone-level CAA.
+ *   3. The zone is empty or the fqdn is empty.
+ *
+ * The comparison is CASE-INSENSITIVE on the suffix but the returned value is a
+ * slice of the ORIGINAL `fqdn`, so a mixed-case name the API sent renders in the
+ * case the API sent it. The API always sends the normalized lowercase form; the
+ * slice-not-lowercase choice means this function cannot itself introduce a
+ * discrepancy between what we display and what we were given.
+ */
+export function relativeName(fqdn, zone) {
+    const f = unroot(fqdn);
+    const z = unroot(zone);
+    if (!f || !z)
+        return undefined;
+    const lf = f.toLowerCase();
+    const lz = z.toLowerCase();
+    // Case 2 — the name IS the zone. No universal relative spelling exists.
+    if (lf === lz)
+        return undefined;
+    // Case 1 — must be a strict subdomain, on a LABEL BOUNDARY. The leading dot is
+    // what makes this a label-boundary test rather than a suffix test: without it,
+    // zone `acme.com` would match `evilacme.com` and return `evil` — the same class
+    // of bug the platform-hostname refusal's leading dot exists to prevent.
+    if (!lf.endsWith(`.${lz}`))
+        return undefined;
+    return f.slice(0, f.length - z.length - 1);
+}
+/**
+ * The pair for one record name, given the domain being attached.
+ *
+ * `zone` is the ATTACHED DOMAIN (`ar.acme.com`), not the registrable domain
+ * (`acme.com`), and that is the correct choice for the reason the transcripts
+ * show: the creator is editing DNS for `acme.com`, so the relative name of
+ * `_vincentt-challenge.ar.acme.com` is `_vincentt-challenge.ar`.
+ *
+ * That means the zone passed here is the REGISTRABLE domain in practice, and the
+ * caller decides which — `recordNamePairs` takes it explicitly rather than
+ * guessing, because a guess at the registrable domain requires a public-suffix
+ * list the CLI deliberately does not ship (`ar.acme.co.uk` would break a
+ * two-label heuristic).
+ */
+export function namePair(fqdn, zone) {
+    return { relative: relativeName(fqdn, zone), fqdn };
+}
+/**
+ * The zone a relative name is relative TO, derived from the attached domain by
+ * dropping its first label.
+ *
+ * `ar.acme.com` → `acme.com`. This is NOT a public-suffix computation and does
+ * not claim to be one: it answers "what will the registrar's form append", and
+ * the registrar whose form appends anything is administering the zone the
+ * attached name sits directly inside. For `ar.acme.co.uk` this yields
+ * `acme.co.uk`, which is the correct zone for that record, while a
+ * public-suffix-based "registrable domain" would also yield `acme.co.uk`. The
+ * two agree wherever the attached name is one label below its zone, which is
+ * every name f16 accepts (root domains are refused at attach).
+ *
+ * Returns undefined for a single-label input, which attach refuses anyway.
+ */
+export function zoneOf(domain) {
+    const d = unroot(domain);
+    const dot = d.indexOf(".");
+    if (dot <= 0)
+        return undefined;
+    const zone = d.slice(dot + 1);
+    return zone.includes(".") ? zone : zone || undefined;
+}
+/**
+ * Every record's name pair, in the order the API sent the records.
+ *
+ * The order is the API's and is never re-sorted here: the transcripts put the
+ * pointer CNAME first, the ownership TXT second and the certificate validation
+ * CNAME third, and that order is the API's to choose. A client that sorted would
+ * put the keep-this-one caption on whichever record happened to land third.
+ */
+export function recordNamePairs(records, domain) {
+    const zone = zoneOf(domain);
+    return records.map((r) => (zone ? namePair(r.name, zone) : { fqdn: r.name }));
+}

package/dist/domain/routedVerbs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Spellings a creator or an agent plausibly types for the domain verb.
+ *
+ * `domains` is the plural of the real verb and is the most likely of the three.
+ * It is NOT pinned in PINNED_VERBS: it names no capability of its own, and
+ * pinning it would freeze a misspelling into the append-only verb surface
+ * forever.
+ */
+export declare const DOMAIN_ROUTED_VERBS: readonly string[];
+export declare function isDomainRoutedVerb(verb: string): boolean;

package/dist/domain/routedVerbs.js

@@ -0,0 +1,30 @@
+// The plausible spellings of `domain` that are NOT the verb, routed to an
+// answer rather than to "unknown command".
+//
+// This is ARGUMENT PARSING. Exit 1, no network call, nothing looked up.
+//
+// It is deliberately NOT the console-only mechanism. That one exists for acts
+// that live on another SURFACE ("rolling back is a console action"); these are
+// acts that live right here under a different spelling, so the answer names the
+// command rather than a screen.
+//
+// Routing them rather than ignoring them is about the actor. A human who types
+// `vincentt domains` and gets "unrecognised command" shrugs and reads the help.
+// AN AGENT RETRIES, or guesses a neighbouring verb, and neither terminates.
+/**
+ * Spellings a creator or an agent plausibly types for the domain verb.
+ *
+ * `domains` is the plural of the real verb and is the most likely of the three.
+ * It is NOT pinned in PINNED_VERBS: it names no capability of its own, and
+ * pinning it would freeze a misspelling into the append-only verb surface
+ * forever.
+ */
+export const DOMAIN_ROUTED_VERBS = [
+    "domains",
+    "custom-domain",
+    "custom-domains",
+    "dns",
+];
+export function isDomainRoutedVerb(verb) {
+    return DOMAIN_ROUTED_VERBS.includes(verb);
+}

package/dist/domain/wire.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The closed state enum (implementation.md § Wire fields).
+ *
+ * `DomainState` is a union of the seven the API can send. An unrecognized state
+ * is NOT coerced into one of these — `parseDomain` keeps the raw string, because
+ * a newer API sending an eighth state must render as itself rather than as a
+ * plausible neighbour. Rendering a state we do not know as `pending` would tell a
+ * creator nothing is wrong when something might be.
+ */
+export declare const DOMAIN_STATES: readonly ["pending", "verified", "live", "failing", "held", "cert_failed", "detached"];
+export type DomainState = (typeof DOMAIN_STATES)[number];
+export declare function isDomainState(s: string): s is DomainState;
+/**
+ * A DNS record the creator must create at their registrar.
+ *
+ * `name` is the FULLY-QUALIFIED name, as the API emits it. It is not normalized,
+ * not lowercased, and not reassembled here.
+ */
+export interface DnsRecord {
+    type: string;
+    name: string;
+    value: string;
+    ttl?: number;
+}
+/**
+ * The closed findings enum (how-it-works.md Scenario 4). Each member carries an
+ * `observed` string.
+ *
+ * The severity is NOT on the wire as a field the CLI trusts blindly — see
+ * `findingSeverity` in copy.ts, which maps the enum to blocking/advisory. That
+ * mapping lives with the copy because the exit code follows the glyph, and the
+ * glyph is a copy decision.
+ */
+export declare const FINDING_CODES: readonly ["TOKEN_MISSING", "TOKEN_MISMATCH", "TOKEN_STALE_PRESENT", "WRONG_RECORD_TYPE", "CNAME_WRONG_TARGET", "CONFLICTING_RECORDS", "UNEXPECTED_AAAA", "PROXY_IN_FRONT", "CAA_BLOCKS_ISSUANCE", "STALE_ACME_CHALLENGE", "VALIDATION_RECORD_GONE", "MALFORMED_ZONE"];
+export type FindingCode = (typeof FINDING_CODES)[number];
+/**
+ * D-44's finding, as a NAMED CONSTANT rather than a literal at each site.
+ *
+ * Two places branch on it — the severity table and the record re-print — and
+ * they were briefly spelled differently, which printed the finding while
+ * silently omitting the record that IS its remedy. A shared symbol makes that
+ * particular disagreement unexpressible.
+ */
+export declare const VALIDATION_RECORD_GONE: FindingCode;
+/**
+ * A finding as the API emits it.
+ *
+ * `observed` is REQUIRED by the design — *"a finding rendered without its
+ * observed value is a restatement of the instructions, and the pattern refuses
+ * one structurally"*. The type makes it required so a renderer cannot omit it;
+ * `parseFinding` drops a finding whose `observed` is absent rather than printing
+ * a half one, and says so in the diagnostics count.
+ */
+export interface Finding {
+    code: string;
+    observed: string;
+    /**
+     * The expected value, as its OWN field, so the renderer can stack it above
+     * `observed` in an aligned pair.
+     *
+     * OPTIONAL, and the optionality is a live cross-repo question rather than a
+     * design choice. Part 2B requires *"every finding carries expected+observed"*
+     * and CLI convention 2 makes the stacked pair structural — but the producer's
+     * `domain.Finding` today carries only `{code, observed}` and folds the
+     * expectation INTO the observed string. Where that happens the pair collapses
+     * into one line and the aligned comparison the ruling rests on is lost.
+     *
+     * The renderer therefore degrades to the observed line alone rather than
+     * inventing an expectation, and never re-splits a folded string: parsing
+     * "(expected …)" back out of `observed` would be the client re-rendering the
+     * one field the wire declares un-restructurable.
+     */
+    expected?: string;
+    /**
+     * The API's own severity, when it sends one (`fault` | `advisory`).
+     *
+     * READ AND HONORED, because the exit code the CLI returns must not disagree
+     * with the state the server put the domain in — and the server is the party
+     * that made the observation. Absent, the renderer falls back to its own
+     * design-derived table.
+     */
+    severity?: string;
+}
+/** A domain row as the API emits it. */
+export interface DomainView {
+    /**
+     * ALWAYS the normalized form. A client sending `AR.Acme.COM.` gets
+     * `ar.acme.com` back and MUST display what it got, not what it sent — so
+     * nothing in the CLI echoes the caller's argument once a response is in hand.
+     */
+    domain: string;
+    /** The raw wire state. `state` is the parsed union when recognized. */
+    rawState: string;
+    state?: DomainState;
+    projectId?: string;
+    projectName?: string;
+    /** Printed verbatim. No client constructs one. */
+    records: DnsRecord[];
+    findings: Finding[];
+    /** ISO8601, when serving stops if unfixed. Null/absent unless `failing`. */
+    holdsAt?: string;
+    attachedAt?: string;
+    /** The project's permanent Vincentt address. Server-computed; never assembled here. */
+    permanentAddress?: string;
+}
+/** The org-scoped list envelope, carrying the count against the entitlement. */
+export interface DomainListView {
+    domains: DomainView[];
+    /** The attached count and the plan's ceiling, as the API resolves them. */
+    count?: number;
+    limit?: number;
+    planName?: string;
+}
+/**
+ * Parse one record. `type`, `name` and `value` are all required: a record
+ * missing any of the three cannot be created at a registrar, and printing a
+ * partial row would send a creator to paste a blank into a form.
+ */
+export declare function parseRecord(raw: unknown): DnsRecord | undefined;
+/**
+ * Parse one finding. A finding with no `observed` is DROPPED rather than
+ * rendered, because the shape's whole contract is that it reports what was seen
+ * — and a finding that restates the instructions is the thing the design refuses.
+ * Dropping is visible: `parseDomain` counts what it dropped.
+ */
+export declare function parseFinding(raw: unknown): Finding | undefined;
+export interface ParsedDomain {
+    domain: DomainView;
+    /** Findings the API sent that carried no `observed`. A defect signal, not a normal state. */
+    droppedFindings: number;
+}
+/**
+ * Parse a domain row.
+ *
+ * `domain` is the only structurally required field: without a hostname there is
+ * nothing to render a row about. Everything else degrades to an absent line.
+ */
+export declare function parseDomain(raw: unknown): ParsedDomain | undefined;
+/** Parse the list envelope. A row that cannot be parsed is skipped, never faked. */
+export declare function parseDomainList(raw: unknown): DomainListView;