@vtechcom/hexcore 2.0.0-beta.1

package/node_modules/@hexcore/shared/dist/cjs/domain.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Hydra Head / Node domain model shared between control-plane and web UI.
+ */
+import { z } from 'zod';
+/** Lifecycle of a Head as tracked by the control-plane (not the on-chain Hydra state). */
+export declare const headStatusSchema: z.ZodEnum<["CONFIGURED", "STARTING", "RUNNING", "STOPPED", "FAILED"]>;
+export type HeadStatus = z.infer<typeof headStatusSchema>;
+/**
+ * On-chain Hydra protocol state, mirrored from the node's Greetings frame.
+ *
+ * Sourced from `Hydra.API.ServerOutput.HeadStatus`. FANNING_OUT landed after
+ * the 2.3.0 tag (selective partial fanout) and is accepted ahead of time so a
+ * newer image degrades to a correct label rather than UNKNOWN.
+ */
+export declare const hydraStateSchema: z.ZodEnum<["IDLE", "INITIALIZING", "OPEN", "CLOSED", "FANOUT_POSSIBLE", "FANNING_OUT", "FINAL", "UNKNOWN"]>;
+export type HydraState = z.infer<typeof hydraStateSchema>;
+export declare const nodeStatusSchema: z.ZodEnum<["CREATED", "STARTING", "RUNNING", "STOPPED", "FAILED"]>;
+export type NodeStatus = z.infer<typeof nodeStatusSchema>;
+export declare const networkSchema: z.ZodEnum<["preprod", "preview", "mainnet"]>;
+export type CardanoNetwork = z.infer<typeof networkSchema>;
+/**
+ * How a head talks to layer 1 — or whether it does at all.
+ *
+ * `offline` is not a variant of the other two: hydra-node's option parser puts
+ * `--offline-head-seed` on a different branch than `--blockfrost` /
+ * `--node-socket`, and mixing them aborts startup. See offline.ts.
+ */
+export declare const chainBackendSchema: z.ZodEnum<["blockfrost", "cardano-node", "offline"]>;
+export type ChainBackend = z.infer<typeof chainBackendSchema>;
+/** Network magic per network — used for --testnet-magic / --mainnet. */
+export declare const NETWORK_MAGIC: Record<CardanoNetwork, number | null>;
+export interface HydraNodeView {
+    id: number;
+    headId: number;
+    /** 0-based index inside the head; drives the deterministic container name. */
+    index: number;
+    name: string;
+    apiPort: number;
+    p2pPort: number;
+    monitoringPort: number;
+    status: NodeStatus;
+    /** Cardano enterprise address funding this node (needs tADA to commit). */
+    cardanoAddress: string | null;
+    hydraVkey: string | null;
+    containerId: string | null;
+    createdAt: string;
+    /**
+     * Which Blockfrost key this node will boot with — never the key itself, so
+     * the value can be shown in a UI that is not trusted with secrets.
+     * 'none' means nothing would be written and the head cannot start.
+     */
+    blockfrostKeySource: BlockfrostKeySource;
+}
+/** Where a node's Blockfrost project id comes from, most specific first. */
+export type BlockfrostKeySource = 'node' | 'head' | 'server' | 'none';
+/**
+ * Logging knobs that apply to every node of a head.
+ *
+ * `quiet` is hydra-node's own `-q`; the rotation pair is Docker's json-file
+ * driver. They live together because they answer one question — how much log a
+ * long-running head is allowed to accumulate — and getting it wrong fills a
+ * disk with JSON nobody reads.
+ */
+export interface HeadLoggingView {
+    /** `--quiet`: hydra-node emits nothing at all. */
+    quiet: boolean;
+    /** Docker json-file `max-size`, in MB, per log file. */
+    maxSizeMb: number;
+    /** Docker json-file `max-file`: how many rotated files are kept. */
+    maxFiles: number;
+}
+/** Offline-mode settings, present only when `chainBackend` is `offline`. */
+export interface OfflineHeadView {
+    /** `--offline-head-seed`, derived from the head id unless overridden. */
+    headSeed: string;
+    /** Lovelace seeded to each node's own address when no UTxO set was supplied. */
+    seedLovelace: number;
+    /** True when the operator supplied the L2 starting UTxO themselves. */
+    customInitialUtxo: boolean;
+    /** True when a shelley genesis was supplied for `--ledger-genesis`. */
+    customLedgerGenesis: boolean;
+}
+export interface HydraHeadView {
+    id: number;
+    name: string;
+    description: string | null;
+    network: CardanoNetwork;
+    chainBackend: ChainBackend;
+    nodeCount: number;
+    contestationPeriod: number;
+    depositPeriod: number;
+    persistenceRotateAfter: number;
+    status: HeadStatus;
+    hydraState: HydraState;
+    hydraNodeImage: string;
+    logging: HeadLoggingView;
+    /** null on every backend but `offline`. */
+    offline: OfflineHeadView | null;
+    /**
+     * Protocol-parameter values pinned for this head, merged over whatever is
+     * fetched at start. Top-level keys only — see protocol-params.ts. Not a
+     * secret, so the UI can show exactly what was frozen and when.
+     */
+    protocolParameterOverrides: Record<string, unknown> | null;
+    /** Last error surfaced while booting/stopping, cleared on next successful action. */
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+    nodes: HydraNodeView[];
+}
+/** Snapshot of one node as reported live by the Hydra WebSocket API. */
+export interface NodeLiveStatus {
+    nodeId: number;
+    name: string;
+    reachable: boolean;
+    hydraState: HydraState;
+    /** Hydra node version reported in Greetings. */
+    version?: string;
+    snapshotUtxoCount?: number;
+    error?: string;
+    /**
+     * Peers this node has reported dropping, and not seen come back.
+     *
+     * Departures rather than membership on purpose: the control-plane attaches
+     * to a node without replaying its history, so it never learns which peers
+     * connected before it was watching. An empty list therefore means "nothing
+     * known to be wrong", not "no peers" — a connected-peer count would sit at
+     * zero on a healthy head and read as a permanent fault.
+     */
+    peersDown?: string[];
+    /**
+     * Whether the container exists and is running, straight from Docker.
+     *
+     * Deliberately separate from `reachable`: a container that is up but whose
+     * API never answers is a different failure from one that is gone, and
+     * collapsing the two is what made a dead head keep reporting RUNNING.
+     */
+    containerRunning?: boolean;
+    /**
+     * Whether the node still has its Hydra network. False after
+     * `NetworkDisconnected`, which is what a peer dropping out looks like from
+     * the surviving nodes — the head's own state stays Open, so this is the only
+     * signal that the head is degraded.
+     */
+    networkConnected?: boolean;
+    /** `InSync` / `CatchingUp` from the node itself. */
+    chainSynced?: 'InSync' | 'CatchingUp';
+    /** Head id the node reports, so two nodes on different heads are visible. */
+    headId?: string;
+    /** ISO timestamp of the last frame received from this node. */
+    lastMessageAt?: string;
+}
+/**
+ * What one node's container is consuming right now, from `docker stats`.
+ *
+ * This is the only number in the product that can be checked against the claim
+ * the node-count ceilings are sized on — ~500 MB of RAM per hydra-node at peak
+ * (docs/PRODUCT.md). A five-node offline head runs five of these on one machine,
+ * so "will this fit" stops being a guess.
+ *
+ * Every measure is nullable and the flags say why: a container that is gone has
+ * no numbers, and reporting 0% CPU for a dead node is worse than reporting
+ * nothing. Docker itself cannot always answer either — see `cpuPercent`.
+ */
+export interface NodeResourceUsage {
+    nodeId: number;
+    /** Container name, so a sample is attributable without the node row. */
+    name: string;
+    /** The container exists and is running. Everything below is null when false. */
+    running: boolean;
+    /**
+     * Percent of ONE host CPU, the same scale `docker stats` prints — so a node
+     * saturating two cores reads as 200%, not 100%. Null when the two samples
+     * Docker compares are identical, which happens on the first read after a
+     * container starts.
+     */
+    cpuPercent: number | null;
+    /** Cores the container may spread over, for reading `cpuPercent` against. */
+    cpuCores: number | null;
+    /**
+     * Resident memory with page cache subtracted, which is what `docker stats`
+     * shows and what actually competes for RAM. The raw cgroup `usage` counts
+     * file cache the kernel will drop under pressure, and reading a hydra-node's
+     * 400 MB trusted-setup file makes that number meaningless.
+     */
+    memoryBytes: number | null;
+    /** The container's limit, or the host's memory when it has none. */
+    memoryLimitBytes: number | null;
+    memoryPercent: number | null;
+    netRxBytes: number | null;
+    netTxBytes: number | null;
+    blockReadBytes: number | null;
+    blockWriteBytes: number | null;
+    pids: number | null;
+    sampledAt: string;
+}
+/** Every node of a head sampled together, so the head's own footprint adds up. */
+export interface HeadResourceUsage {
+    headId: number;
+    nodes: NodeResourceUsage[];
+    /** Sum over running nodes. Null when nothing could be sampled. */
+    totalMemoryBytes: number | null;
+    totalCpuPercent: number | null;
+    sampledAt: string;
+}
+/**
+ * What this server can actually do, as opposed to what it is configured to
+ * prefer. The UI needs the difference: a backend whose credential is missing
+ * has to be steered away from at creation, not discovered at boot.
+ *
+ * Deliberately carries no secrets — `blockfrost.configured` is a boolean, never
+ * the project id.
+ */
+export interface SystemConfig {
+    network: CardanoNetwork;
+    /** Backend a head gets when the create request names none. */
+    defaultChainBackend: ChainBackend;
+    defaultHydraNodeImage: string;
+    maxActiveNodes: number;
+    stateDir: string;
+    blockfrost: {
+        /** A server-wide BLOCKFROST_PROJECT_ID exists to fall back on. */
+        configured: boolean;
+    };
+    cardanoNode: {
+        /** CARDANO_NODE_SOCKET is set. */
+        configured: boolean;
+        /** …and the socket exists and is readable/writable right now. */
+        available: boolean;
+        /** Why not, when unavailable. */
+        reason?: string;
+        socketPath: string | null;
+    };
+}
+/**
+ * Boot progress for a head that is starting.
+ *
+ * Starting a head is not one action, it is six, and on a cold machine the image
+ * pull alone can run for minutes. A spinner covering all of that tells the
+ * operator nothing about whether anything is happening, and when it fails, the
+ * one error left on the row rarely says which part gave up. This is the same
+ * sequence the control-plane actually walks, reported as it happens.
+ */
+export type BootStepState = 'pending' | 'active' | 'done' | 'failed';
+export interface BootStep {
+    key: string;
+    label: string;
+    state: BootStepState;
+    /** Live sub-status: pull progress, "2/3 nodes ready", the failure reason. */
+    detail?: string;
+    startedAt?: string;
+    endedAt?: string;
+}
+export interface BootLogLine {
+    at: string;
+    level: 'info' | 'warn' | 'error';
+    /** `hexcore` for the control-plane's own lines, else the container name. */
+    source: string;
+    message: string;
+}
+export interface HeadBootProgress {
+    headId: number;
+    status: 'running' | 'succeeded' | 'failed';
+    startedAt: string;
+    endedAt?: string;
+    steps: BootStep[];
+    /**
+     * The control-plane's own progress lines interleaved with what the
+     * containers printed while we waited for them. hydra-node explains its own
+     * refusals — an unknown flag, a bad key, a chain it cannot reach — and
+     * without this the operator only ever saw "node never became ready".
+     */
+    logs: BootLogLine[];
+    /** Set when status is `failed`. */
+    error?: string;
+}
+export interface HeadLiveStatus {
+    headId: number;
+    status: HeadStatus;
+    hydraState: HydraState;
+    nodes: NodeLiveStatus[];
+    checkedAt: string;
+    /**
+     * The head is up but not whole — some containers are gone, some nodes are
+     * unreachable, or a node has lost its Hydra network.
+     *
+     * A separate axis from `status` on purpose. A three-node head with one node
+     * down is still RUNNING and still serving, but calling that healthy is how
+     * a half-dead head goes unnoticed until someone asks why a snapshot never
+     * confirms.
+     */
+    degraded: boolean;
+    /** Why, when degraded. Empty otherwise. */
+    degradedReasons: string[];
+    /** Containers running, out of the head's node count. */
+    containersRunning: number;
+}
+//# sourceMappingURL=domain.d.ts.map

package/node_modules/@hexcore/shared/dist/cjs/domain.d.ts.map

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

package/node_modules/@hexcore/shared/dist/cjs/domain.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NETWORK_MAGIC = exports.chainBackendSchema = exports.networkSchema = exports.nodeStatusSchema = exports.hydraStateSchema = exports.headStatusSchema = void 0;
+/**
+ * Hydra Head / Node domain model shared between control-plane and web UI.
+ */
+const zod_1 = require("zod");
+/** Lifecycle of a Head as tracked by the control-plane (not the on-chain Hydra state). */
+exports.headStatusSchema = zod_1.z.enum([
+    'CONFIGURED', // rows + keys exist on disk, no containers
+    'STARTING', // containers created, waiting for all nodes to greet
+    'RUNNING', // all nodes answered Greetings
+    'STOPPED', // containers removed on purpose
+    'FAILED', // boot failed, containers cleaned up
+]);
+/**
+ * On-chain Hydra protocol state, mirrored from the node's Greetings frame.
+ *
+ * Sourced from `Hydra.API.ServerOutput.HeadStatus`. FANNING_OUT landed after
+ * the 2.3.0 tag (selective partial fanout) and is accepted ahead of time so a
+ * newer image degrades to a correct label rather than UNKNOWN.
+ */
+exports.hydraStateSchema = zod_1.z.enum([
+    'IDLE',
+    'INITIALIZING',
+    'OPEN',
+    'CLOSED',
+    'FANOUT_POSSIBLE',
+    'FANNING_OUT',
+    'FINAL',
+    'UNKNOWN',
+]);
+exports.nodeStatusSchema = zod_1.z.enum(['CREATED', 'STARTING', 'RUNNING', 'STOPPED', 'FAILED']);
+exports.networkSchema = zod_1.z.enum(['preprod', 'preview', 'mainnet']);
+/**
+ * How a head talks to layer 1 — or whether it does at all.
+ *
+ * `offline` is not a variant of the other two: hydra-node's option parser puts
+ * `--offline-head-seed` on a different branch than `--blockfrost` /
+ * `--node-socket`, and mixing them aborts startup. See offline.ts.
+ */
+exports.chainBackendSchema = zod_1.z.enum(['blockfrost', 'cardano-node', 'offline']);
+/** Network magic per network — used for --testnet-magic / --mainnet. */
+exports.NETWORK_MAGIC = {
+    preprod: 1,
+    preview: 2,
+    mainnet: null, // mainnet uses --mainnet, no magic
+};
+//# sourceMappingURL=domain.js.map

package/node_modules/@hexcore/shared/dist/cjs/domain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"domain.js","sourceRoot":"","sources":["../../src/domain.ts"],"names":[],"mappings":";;;AAAA;;GAEG;AACH,6BAAwB;AAExB,0FAA0F;AAC7E,QAAA,gBAAgB,GAAG,OAAC,CAAC,IAAI,CAAC;IACnC,YAAY,EAAE,2CAA2C;IACzD,UAAU,EAAE,qDAAqD;IACjE,SAAS,EAAE,+BAA+B;IAC1C,SAAS,EAAE,gCAAgC;IAC3C,QAAQ,EAAE,qCAAqC;CAClD,CAAC,CAAC;AAGH;;;;;;GAMG;AACU,QAAA,gBAAgB,GAAG,OAAC,CAAC,IAAI,CAAC;IACnC,MAAM;IACN,cAAc;IACd,MAAM;IACN,QAAQ;IACR,iBAAiB;IACjB,aAAa;IACb,OAAO;IACP,SAAS;CACZ,CAAC,CAAC;AAGU,QAAA,gBAAgB,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;AAGnF,QAAA,aAAa,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;AAGvE;;;;;;GAMG;AACU,QAAA,kBAAkB,GAAG,OAAC,CAAC,IAAI,CAAC,CAAC,YAAY,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC,CAAC;AAGpF,wEAAwE;AAC3D,QAAA,aAAa,GAA0C;IAChE,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,CAAC;IACV,OAAO,EAAE,IAAI,EAAE,mCAAmC;CACrD,CAAC"}

package/node_modules/@hexcore/shared/dist/cjs/hydra-versions.d.ts

@@ -0,0 +1,279 @@
+/**
+ * Per-version hydra-node argv profiles.
+ *
+ * hydra-node's flag set moves between releases: 0.22.x has `--blockfrost` and
+ * `--network` but neither `--unsynced-period` nor the Blockfrost timeout knobs,
+ * which arrived in the 2.x line. An unknown flag aborts hydra-node during
+ * option parsing, so the container dies instantly and the head reports a
+ * generic "node never became ready" that points nowhere near the real cause.
+ *
+ * This table is the declared answer for the versions we ship support for: which
+ * flags exist, and what values to pass when the operator has not overridden
+ * them. Adding a hydra-node release is deliberately a code change — a new entry
+ * here plus a bump of HYDRA_NODE_IMAGE — so a version's argv is reviewed and
+ * tested rather than guessed at runtime.
+ *
+ * Images that match no entry (a fork, a `master` tag, a release newer than this
+ * build) are not rejected: the control-plane falls back to probing
+ * `hydra-node --help`. See capabilities.ts.
+ *
+ * Lives in shared because the UI lists the same versions in the create form
+ * that the control-plane accepts.
+ */
+import type { ChainBackend } from './domain';
+/**
+ * A known upstream defect in some range of hydra-node releases.
+ *
+ * Separate from the flag table because it answers a different question. Flags
+ * decide whether a head can BOOT; this decides whether the version someone is
+ * about to pin for the life of a head is one they will regret. A head's image
+ * cannot be changed under running persistence, so the warning has to arrive
+ * while the create form is open, not the first time the bug bites.
+ *
+ * Matched by version range rather than by profile, so it also covers an image
+ * this build ships no profile for — a 2.2.0 pinned by hand is affected by the
+ * same bugs as one we declare.
+ */
+/**
+ * The machine the containers will actually run on.
+ *
+ * It belongs in this table because one of the things that decides whether an
+ * image works is not the image at all — every upstream hydra-node is amd64-only,
+ * and that is invisible on an amd64 host and fatal on Apple Silicon.
+ *
+ * OS as well as architecture, because on arm64 the two produce different
+ * failures and want different answers:
+ *
+ *  - **darwin-arm64**: Docker Desktop runs the amd64 image under Rosetta, so it
+ *    starts, stalls inside the KZG warm-up, and prints nothing. The worst kind
+ *    of failure — it looks like a timeout with no cause.
+ *  - **linux-arm64**: without qemu binfmt the daemon refuses the image outright
+ *    ("no matching manifest for linux/arm64"), which is loud and self-explaining.
+ *
+ * `unknown` is a real answer, not a placeholder: an older control-plane, or a
+ * client asking before the server has said. Anything keyed on this must decide
+ * deliberately what to do with it.
+ */
+export type HostPlatform = 'darwin-arm64' | 'darwin-x64' | 'linux-arm64' | 'linux-x64' | 'unknown';
+/** Every platform this table distinguishes, for entries that apply to all. */
+export declare const HOST_PLATFORMS: readonly HostPlatform[];
+/** True on a platform whose Docker cannot run an amd64 image natively. */
+export declare function isArm64(platform: HostPlatform): boolean;
+export interface HydraKnownIssue {
+    /**
+     * Issue number on cardano-scaling/hydra.
+     *
+     * Absent when the defect has no upstream issue — a packaging or platform
+     * fact rather than a bug report. `url` then points at our own record of it,
+     * so the claim is still checkable. Never invent a number to fill this in.
+     */
+    id?: number;
+    url: string;
+    title: string;
+    /** What it means for someone running this version, in plain terms. */
+    impact: string;
+    /**
+     * `blocker` — the head stops or dies. `warning` — degraded but usable.
+     * Nothing here refuses a version: an operator may have a reason, and
+     * refusing would make an existing head unrunnable after an upgrade.
+     */
+    severity: 'blocker' | 'warning';
+    /** First release WITHOUT the bug. Undefined means still open upstream. */
+    fixedIn?: string;
+    /**
+     * Oldest release the defect is known to affect.
+     *
+     * Bounds the range at the bottom so a 2.x bug is not claimed against the
+     * 0.22 line, which is a different protocol with different scripts and a
+     * different head logic — the code the issue points at often does not exist
+     * there. Omit only when the defect plainly predates every version we offer.
+     * Guessing here is worse than staying quiet: a warning nobody can verify is
+     * one people learn to click past.
+     */
+    affectedFrom?: string;
+    /** Only bites on these chain backends; omitted means all of them. */
+    backends?: ChainBackend[];
+    /**
+     * Only affects images whose full REFERENCE matches this.
+     *
+     * The escape hatch from version-range matching, and it exists because one
+     * defect here is not a property of the version at all. Upstream's images are
+     * amd64-only; a rebuild of the identical source for arm64 carries the same
+     * version number and is precisely the fix. Matched on the whole reference
+     * rather than the tag, since the registry and repository are what say who
+     * built it — `tagPattern` on a profile does the opposite, deliberately.
+     *
+     * Use it only when the defect really does travel with the build rather than
+     * the code. Anything the source contains belongs in the version range, where
+     * a private mirror of an affected version is still covered.
+     */
+    imagePattern?: RegExp;
+    /**
+     * Only bites on these platforms.
+     *
+     * A blocker badge shown to everyone on a version most of them can run
+     * perfectly is not caution, it is the thing that teaches people to click
+     * past warnings. An issue carrying this is suppressed when the host is known
+     * to be something else — and shown when the host is `unknown`, because
+     * failing to warn is the worse of the two mistakes.
+     */
+    hostPlatforms?: HostPlatform[];
+}
+/**
+ * Defects worth warning about, newest first.
+ *
+ * Add an entry when upstream confirms one that changes whether a version is
+ * safe to pin — with the issue link, so the claim is checkable and can be
+ * retired when it is fixed.
+ */
+export declare const HYDRA_KNOWN_ISSUES: readonly HydraKnownIssue[];
+/**
+ * Numeric version from an image tag, or null when it is not a release tag
+ * (`master`, a fork, a digest). Pre-release suffixes are ignored: `2.3.0-rc1`
+ * is treated as 2.3.0, which is the right call for "does this carry the fix".
+ */
+export declare function parseVersionTag(tag: string): [number, number, number] | null;
+/** True when `tag` names a release strictly older than `other`. */
+export declare function isVersionBefore(tag: string, other: string): boolean;
+/**
+ * Known issues that apply to an image, optionally narrowed to one backend.
+ *
+ * An unparseable tag yields nothing rather than everything: we genuinely do not
+ * know what a `master` build contains, and warning about every open issue on a
+ * version that may well have the fix is noise that trains people to ignore it.
+ */
+export declare function knownIssuesFor(image: string, backend?: ChainBackend, platform?: HostPlatform): HydraKnownIssue[];
+/** Which flags an image's option parser accepts. */
+export interface HydraFlagSupport {
+    /** `--unsynced-period SECONDS` — needed to survive Blockfrost tip drift. */
+    unsyncedPeriod: boolean;
+    /** `--blockfrost-query-timeout` / `--blockfrost-retry-timeout`. */
+    blockfrostTimeouts: boolean;
+    /** `--network NETWORK`, selecting pre-published scripts. */
+    network: boolean;
+    /** `--blockfrost FILE`. Absent on very old builds. */
+    blockfrost: boolean;
+    /**
+     * `--offline-head-seed` — hydra-node runs with its layer-1 interface
+     * disabled. Gated like the rest because it is the flag that selects the
+     * offline branch of the option parser: an image without it treats the head
+     * as online and dies on the first unknown option.
+     */
+    offline: boolean;
+}
+/** Argument values a head boots with, once profile and overrides are merged. */
+export interface HydraVersionArgs {
+    unsyncedPeriod: number;
+    blockfrostQueryTimeout: number;
+    blockfrostRetryTimeout: number;
+    /**
+     * Flags this version needs that no other version does, passed through
+     * verbatim. The escape hatch that keeps "support a new release" a data
+     * change here instead of a new branch in argv.ts.
+     */
+    extraArgs: string[];
+}
+export interface HydraVersionProfile {
+    /** Stable key, also what the API and events report. */
+    id: string;
+    /** Human label for the create form. */
+    label: string;
+    /** Image this profile installs when picked in the UI. */
+    image: string;
+    /**
+     * Tags this profile claims, matched against the tag alone (not the whole
+     * ref) so a private mirror of the same version still resolves.
+     */
+    tagPattern: RegExp;
+    flags: HydraFlagSupport;
+    args: HydraVersionArgs;
+    /** One line on what picking this version means, shown under the select. */
+    summary: string;
+    /**
+     * Platforms on which this is the version a new head should get.
+     *
+     * Not a plain boolean, because the right default genuinely differs by
+     * machine: upstream publishes amd64 only, and on Apple Silicon the image
+     * that boots is a rebuild of the same source. A single recommendation would
+     * have to be wrong for one of the two.
+     */
+    recommendedOn?: HostPlatform[];
+}
+/**
+ * Newest first — `findVersionProfile` returns the first match, so a more
+ * specific pattern must come before a broader one.
+ */
+export declare const HYDRA_VERSION_PROFILES: readonly HydraVersionProfile[];
+/**
+ * Values used when an image matches no profile, so an unrecognised image still
+ * boots with the same tuning the 2.x line gets. Whether the flags are actually
+ * passed is decided separately, by probing the image.
+ */
+export declare const FALLBACK_HYDRA_ARGS: HydraVersionArgs;
+/**
+ * The tag part of an image reference.
+ *
+ * Written by hand rather than with a split(':') because both `localhost:5000/x`
+ * (registry port, no tag) and `x@sha256:…` (digest, no tag) would otherwise
+ * report a tag that does not exist and match the wrong profile.
+ */
+export declare function imageTag(image: string): string;
+/** The profile claiming this image, or undefined when it must be probed. */
+export declare function findVersionProfile(image: string): HydraVersionProfile | undefined;
+/** Overrides an operator set in the environment; unset keys keep the profile's value. */
+export interface HydraArgOverrides {
+    unsyncedPeriod?: number;
+    blockfrostQueryTimeout?: number;
+    blockfrostRetryTimeout?: number;
+}
+/**
+ * Merge, in order: explicit operator override, then the version's own default,
+ * then the fallback. An override is deliberately allowed to win over the
+ * profile — someone who set HYDRA_UNSYNCED_PERIOD for a reason should not have
+ * it silently reverted by a version bump.
+ */
+export declare function resolveHydraArgs(profile: HydraVersionProfile | undefined, overrides?: HydraArgOverrides): HydraVersionArgs;
+/** Serialisable view of a profile — RegExp does not survive JSON. */
+export interface HydraVersionInfo {
+    id: string;
+    label: string;
+    image: string;
+    summary: string;
+    recommended: boolean;
+    flags: HydraFlagSupport;
+    args: HydraVersionArgs;
+    /**
+     * Upstream defects this version carries, resolved from the version range so
+     * the UI does not have to. Backend filtering stays on the client, which is
+     * the only side that knows which backend the form has selected.
+     */
+    knownIssues: HydraKnownIssue[];
+}
+export declare function toVersionInfo(profile: HydraVersionProfile, platform?: HostPlatform): HydraVersionInfo;
+/** Response of `GET /api/hydra/versions`. */
+export interface HydraVersionsResponse {
+    /** What a head gets when the caller names no image (HYDRA_NODE_IMAGE). */
+    defaultImage: string;
+    /** Profile id claiming `defaultImage`, or null when it will be probed. */
+    defaultProfileId: string | null;
+    profiles: HydraVersionInfo[];
+    /**
+     * The platform the containers will run on, as the SERVER sees it.
+     *
+     * Sent because which image works is partly a property of the machine, and
+     * only the control-plane knows which machine that is — the browser may be
+     * on a different one entirely. It is what makes "recommended" mean something
+     * a reader can check rather than a badge that appears for no stated reason.
+     */
+    hostPlatform: HostPlatform;
+}
+/**
+ * Map Node's `process.platform` and `process.arch` onto the platforms this
+ * table distinguishes.
+ *
+ * Anything outside the four becomes `unknown` rather than being carried
+ * through: the table only holds evidence about those, and a claim about a
+ * FreeBSD s390x host is one nobody has checked.
+ */
+export declare function toHostPlatform(os: string, arch: string): HostPlatform;
+//# sourceMappingURL=hydra-versions.d.ts.map

package/node_modules/@hexcore/shared/dist/cjs/hydra-versions.d.ts.map

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