@omnitron-dev/omnitron 0.1.3 → 0.3.0

package/dist/infrastructure/presets/torrc.js

@@ -0,0 +1,153 @@
+/**
+ * The torrc an onion service runs on, and why each line is in it.
+ *
+ * Built here rather than by shell inside the container. The previous version
+ * assembled it with `cat`, `jq` and a `while read` loop at runtime, which
+ * meant the one file that decides whether a service is anonymous could not
+ * be read without starting a container, and could not be tested at all. A
+ * hardening option that is silently dropped by a quoting mistake looks
+ * exactly like one that was never asked for.
+ *
+ * Everything here is a real Tor option, checked against `tor --version`
+ * 0.4.9.12 — the newest in Alpine 3.21, measured rather than assumed.
+ *
+ * The threat this is written against: an adversary who wants to learn which
+ * host runs the service, or to make it stop. Not an adversary who has the
+ * host — that one has the keys, and no torrc helps.
+ */
+/**
+ * Per-service defence tuning.
+ *
+ * The introduction point is where an onion service is cheapest to attack:
+ * anyone can ask it to relay an introduction, and the service pays to
+ * answer. These are the two mechanisms Tor gives for that, and neither is
+ * on by default.
+ */
+const INTRO_DOS_RATE_PER_SEC = 25;
+const INTRO_DOS_BURST_PER_SEC = 200;
+/** PoW: how fast the service dequeues client requests, and the burst it tolerates. */
+const POW_QUEUE_RATE = 250;
+const POW_QUEUE_BURST = 2500;
+/** A single client's streams on one rendezvous circuit. */
+const MAX_STREAMS_PER_CIRCUIT = 128;
+export function renderTorrc(inputs) {
+    const lines = [
+        '# =====================================================================',
+        '# Onion-service-only Tor, generated by omnitron. Do not edit in place —',
+        '# the container rewrites this file on every start.',
+        '# =====================================================================',
+        '',
+        '# Identity. Tor drops privileges to this account after binding.',
+        'User tor',
+        '',
+        '# --- This process is not a relay, not a proxy, and not a client ------',
+        '#',
+        '# A SOCKS port would make the host an open proxy on its docker network;',
+        '# an ORPort would make it a relay, which publishes its address in the',
+        '# consensus — the one fact an onion service exists to withhold.',
+        'SocksPort 0',
+        'ORPort 0',
+        'DirPort 0',
+        'ControlPort 0',
+        'ClientOnly 1',
+        'ExitRelay 0',
+        'ExitPolicy reject *:*',
+        'ExitPolicy reject6 *:*',
+        'BridgeRelay 0',
+        'PublishServerDescriptor 0',
+        '',
+        '# --- Anonymity ------------------------------------------------------',
+        '#',
+        '# Single-hop mode trades the service\'s anonymity for latency. It is off',
+        '# by default and named here so that turning it on is a visible edit and',
+        '# not an omission.',
+        'HiddenServiceSingleHopMode 0',
+        'HiddenServiceNonAnonymousMode 0',
+        '',
+        '# Guard discovery is the attack that finds the host behind an onion',
+        '# service: watch which relays it builds circuits through, narrow the',
+        '# set, then attack what is left. Tor 0.4.7+ keeps layer-2 and layer-3',
+        '# guards for onion services automatically (vanguards-lite) — this',
+        '# states the entry layer it rests on.',
+        'UseEntryGuards 1',
+        'NumEntryGuards 1',
+        'EnforceDistinctSubnets 1',
+        '',
+        '# Padding hides the shape of traffic from whoever can see the link to',
+        '# the guard. The reduced variants exist for battery-powered clients and',
+        '# cost anonymity; a server has no reason to take that trade.',
+        'ConnectionPadding 1',
+        'ReducedConnectionPadding 0',
+        'CircuitPadding 1',
+        'ReducedCircuitPadding 0',
+        '',
+        '# IPv4 only. A host reachable both ways is two chances to be correlated,',
+        '# and onion traffic needs neither.',
+        'ClientUseIPv4 1',
+        'ClientUseIPv6 0',
+        'ClientPreferIPv6ORPort 0',
+        '',
+        '# --- What is written down -------------------------------------------',
+        '#',
+        '# SafeLogging scrubs addresses from the log. `notice` is the highest',
+        '# level that never logs a circuit or a stream: `info` and `debug` do,',
+        '# and a debug log from an onion service is a deanonymisation waiting to',
+        '# be read by whoever gets the file.',
+        'SafeLogging 1',
+        'Log notice stdout',
+        'LogTimeGranularity 1000',
+        'LogMessageDomains 0',
+        '',
+        '# Nothing about this service belongs on disk beyond its keys.',
+        'DataDirectory /var/lib/tor',
+        'DataDirectoryGroupReadable 0',
+        'AvoidDiskWrites 1',
+        'RunAsDaemon 0',
+        '',
+        '# --- Process hardening ----------------------------------------------',
+        '#',
+        '# NoExec stops tor executing anything at all, which removes the class',
+        '# of bug where a malformed input becomes a command. DisableDebugger-',
+        '# Attachment keeps another process on the host from reading the keys',
+        '# out of memory.',
+        'NoExec 1',
+        'DisableDebuggerAttachment 1',
+        'HardwareAccel 1',
+        '',
+    ];
+    for (const service of inputs.services) {
+        lines.push(`# --- Hidden service: ${service.name} ---`, `HiddenServiceDir /var/lib/tor/${service.name}`, 
+        // v3 only. v2 was removed from Tor, and its addresses were 80-bit
+        // truncated hashes — brute-forceable to a lookalike.
+        'HiddenServiceVersion 3', `HiddenServicePort ${service.virtualPort} ${service.target}`, '', '# The introduction point is where this service is cheapest to attack:', '# anyone may ask it to relay an introduction, and the service pays to', '# answer. Neither defence is on by default.', 'HiddenServiceEnableIntroDoSDefense 1', `HiddenServiceEnableIntroDoSRatePerSec ${INTRO_DOS_RATE_PER_SEC}`, `HiddenServiceEnableIntroDoSBurstPerSec ${INTRO_DOS_BURST_PER_SEC}`, 'HiddenServicePoWDefensesEnabled 1', `HiddenServicePoWQueueRate ${POW_QUEUE_RATE}`, `HiddenServicePoWQueueBurst ${POW_QUEUE_BURST}`, '', '# One client must not be able to hold the service open indefinitely.', `HiddenServiceMaxStreams ${MAX_STREAMS_PER_CIRCUIT}`, 'HiddenServiceMaxStreamsCloseCircuit 1', '', '# The key directory is this service. Group-readable means any process', '# in the container s group can copy the identity.', 'HiddenServiceDirGroupReadable 0');
+        if (service.authorizedClients && service.authorizedClients.length > 0) {
+            lines.push('', `# ${service.authorizedClients.length} authorized client(s): without one of`, '# these keys a client cannot decrypt the descriptor, so the service', '# is not merely closed to them — it is undiscoverable.');
+        }
+        lines.push('');
+    }
+    if (inputs.extra && inputs.extra.length > 0) {
+        lines.push('# --- Operator additions ---', ...inputs.extra, '');
+    }
+    return lines.join('\n');
+}
+/**
+ * The `.auth` files that make client authorization real.
+ *
+ * Returned separately from the torrc because they are not torrc lines: tor
+ * reads them from `<HiddenServiceDir>/authorized_clients/`, and a key that
+ * never reaches that directory is a restriction that silently does not
+ * exist.
+ */
+export function authorizedClientFiles(services) {
+    const files = [];
+    for (const service of services) {
+        for (const [index, key] of (service.authorizedClients ?? []).entries()) {
+            files.push({
+                path: `/var/lib/tor/${service.name}/authorized_clients/client-${index + 1}.auth`,
+                content: `${key}\n`,
+            });
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=torrc.js.map

package/dist/infrastructure/presets/torrc.js.map

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

package/dist/infrastructure/presets/types.d.ts

@@ -31,6 +31,23 @@ export interface IServicePreset {
     defaultDocker: Partial<IDockerServiceConfig>;
     /** Default credentials (e.g., { user: 'postgres', password: 'postgres' }) */
     defaultSecrets: Record<string, string>;
+    /**
+     * Build the container command from the user's `config` block.
+     *
+     * Without this the command is whatever `defaultDocker.command` hardcodes,
+     * and the tuning options the service config declares reach nothing. That
+     * was the state of things: `PostgresServiceConfig.config` documented six
+     * settings with defaults, the postgres preset hardcoded `max_connections`
+     * and `shared_buffers` into its command, and an operator who raised
+     * `sharedBuffers` to 4GB in omnitron.stacks.json got 256MB and no word
+     * about it. `config.config` was carried as far as `_presetConfig` and
+     * handed only to `postProvision`, which reads `databases` and nothing
+     * else.
+     *
+     * Falls back to `defaultDocker.command` when a preset does not implement
+     * it, and is overridden entirely by an explicit `docker.command`.
+     */
+    buildCommand?: (userConfig: Record<string, unknown>) => string[];
     /**
      * Post-provision hook — runs after the container is healthy.
      * Used for setup like CREATE DATABASE, creating S3 buckets, etc.

package/dist/infrastructure/presets/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/presets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,SAAS,EACV,MAAM,aAAa,CAAC;AAMrB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAEnF,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IAErB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC,yCAAyC;IACzC,kBAAkB,EAAE,mBAAmB,CAAC;IAExC,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE7C,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxF;AAMD,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,qDAAqD;IACrD,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,6BAA6B;IAC7B,MAAM,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE/B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAE7C,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC,qCAAqC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEvC,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAE7C,sBAAsB;IACtB,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/infrastructure/presets/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AACjE,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,SAAS,EACV,MAAM,aAAa,CAAC;AAMrB;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,0FAA0F;IAC1F,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,IAAI,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAEnF,2BAA2B;IAC3B,YAAY,EAAE,MAAM,CAAC;IAErB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAErC,yCAAyC;IACzC,kBAAkB,EAAE,mBAAmB,CAAC;IAExC,0EAA0E;IAC1E,aAAa,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAE7C,6EAA6E;IAC7E,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvC;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,EAAE,CAAC;IAEjE;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9D;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxF;AAMD,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,qDAAqD;IACrD,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACxD,6BAA6B;IAC7B,MAAM,EAAE,OAAO,CAAC;CACjB;AAMD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE/B,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAE7C,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC,qCAAqC;IACrC,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEvC,mCAAmC;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,CAAC;IAE7C,sBAAsB;IACtB,SAAS,CAAC,EAAE,cAAc,CAAC;CAC5B"}

package/dist/infrastructure/provisioning-outcome.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Whether provisioning actually provisioned anything.
+ *
+ * `provision()` set `state.ready = true` and logged "Infrastructure
+ * provisioned and healthy" as the last two statements of its `try`,
+ * unconditionally. Every service reconciles inside a `Promise.all` whose
+ * per-service `catch` records `status: 'exited'` and continues, so a run in
+ * which every container failed ended exactly like a run in which all of them
+ * came up.
+ *
+ * `omnitron infra up` then printed
+ *
+ *     Infrastructure ready:
+ *
+ * as a heading, before looking at anything, and listed whatever
+ * `state.services` happened to hold. An empty object printed the heading and
+ * nothing else — and an empty enumeration of problems reads as "no
+ * problems". Observed three times in one shift on a host under memory
+ * pressure, with `daos-dev-postgres` and `daos-dev-redis` absent from
+ * `docker ps -a` entirely at the moment it said so.
+ *
+ * The cost is separate from the cause. A control plane that reports health
+ * when the database is gone sends whoever reads it to look at their own
+ * change: one colleague reverted a correct fix after reading
+ * `Module "TitanRedisModule" failed to initialize`, because the line above it
+ * said the infrastructure was fine. The full error said
+ * `Redis client "default" connection timed out`.
+ *
+ * Three states have to be distinguishable, and two of them looked identical
+ * because both produced an empty list of complaints:
+ *
+ *   - declared, present, running;
+ *   - declared, present, not running — an error to show;
+ *   - declared and MISSING — nothing even tried, which is the one that
+ *     looks like success.
+ */
+import type { ContainerState, ContainerStatus } from './types.js';
+export interface ServiceOutcome {
+    name: string;
+    image: string | undefined;
+    status: ContainerStatus | 'missing';
+    error: string | undefined;
+}
+export interface ProvisioningOutcome {
+    /** True only when everything declared is present and running. */
+    ready: boolean;
+    /** Nothing was declared — not the same as everything being fine. */
+    empty: boolean;
+    running: ServiceOutcome[];
+    /** Present and not running, or running and reporting unhealthy. */
+    failed: ServiceOutcome[];
+    /** Declared, and absent from the state entirely. */
+    missing: ServiceOutcome[];
+}
+export declare function summariseProvisioning(desired: readonly {
+    name: string;
+    image?: string | undefined;
+}[], services: Readonly<Record<string, ContainerState>>): ProvisioningOutcome;
+/** One line saying what happened, for a log that has to be readable alone. */
+export declare function describeProvisioning(outcome: ProvisioningOutcome): string;
+/** What the node did about services that are not containers (`reconcileHostServices`). */
+export interface HostServicesOutcome {
+    settled: readonly string[];
+    /** Refused by the plan, or failed while it was carried out. */
+    failed: ReadonlyArray<{
+        name: string;
+        status: string;
+        error: string | null;
+    }>;
+}
+/**
+ * The node's verdict on everything it was asked to bring up.
+ *
+ * Readiness counted the containers and the host services' REFUSALS, and not a
+ * host service that failed while its plan was carried out. Measured on the
+ * test node, 2026-09-23: bitcoind's start failed — `could not start bitcoind: `
+ * — and the node answered `ready: true` with «Infrastructure provisioned and
+ * healthy (5 services)», the failure sitting in `failed` beside it; the master
+ * logged that sentence and the deployment reported `6/6 apps online`.
+ */
+export declare function provisioningVerdict(outcome: ProvisioningOutcome, hosted: HostServicesOutcome): {
+    ready: boolean;
+    detail: string;
+};
+//# sourceMappingURL=provisioning-outcome.d.ts.map

package/dist/infrastructure/provisioning-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioning-outcome.d.ts","sourceRoot":"","sources":["../../src/infrastructure/provisioning-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC;IACpC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,KAAK,EAAE,OAAO,CAAC;IACf,oEAAoE;IACpE,KAAK,EAAE,OAAO,CAAC;IACf,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,mEAAmE;IACnE,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,oDAAoD;IACpD,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAcD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAAE,EAChE,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,GACjD,mBAAmB,CA+CrB;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAQzE;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,+DAA+D;IAC/D,MAAM,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,mBAAmB,GAC1B;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAKpC"}

package/dist/infrastructure/provisioning-outcome.js

@@ -0,0 +1,122 @@
+/**
+ * Whether provisioning actually provisioned anything.
+ *
+ * `provision()` set `state.ready = true` and logged "Infrastructure
+ * provisioned and healthy" as the last two statements of its `try`,
+ * unconditionally. Every service reconciles inside a `Promise.all` whose
+ * per-service `catch` records `status: 'exited'` and continues, so a run in
+ * which every container failed ended exactly like a run in which all of them
+ * came up.
+ *
+ * `omnitron infra up` then printed
+ *
+ *     Infrastructure ready:
+ *
+ * as a heading, before looking at anything, and listed whatever
+ * `state.services` happened to hold. An empty object printed the heading and
+ * nothing else — and an empty enumeration of problems reads as "no
+ * problems". Observed three times in one shift on a host under memory
+ * pressure, with `daos-dev-postgres` and `daos-dev-redis` absent from
+ * `docker ps -a` entirely at the moment it said so.
+ *
+ * The cost is separate from the cause. A control plane that reports health
+ * when the database is gone sends whoever reads it to look at their own
+ * change: one colleague reverted a correct fix after reading
+ * `Module "TitanRedisModule" failed to initialize`, because the line above it
+ * said the infrastructure was fine. The full error said
+ * `Redis client "default" connection timed out`.
+ *
+ * Three states have to be distinguishable, and two of them looked identical
+ * because both produced an empty list of complaints:
+ *
+ *   - declared, present, running;
+ *   - declared, present, not running — an error to show;
+ *   - declared and MISSING — nothing even tried, which is the one that
+ *     looks like success.
+ */
+/**
+ * A container that is running is not necessarily working.
+ *
+ * Docker's own health probe is the only thing here that has looked inside,
+ * so `unhealthy` outranks `running`. `starting` does not: a container in its
+ * first probe window is not yet a failure, and calling it one would make
+ * every provisioning run fail for the seconds before the first check.
+ */
+function isUp(state) {
+    return state.status === 'running' && state.health !== 'unhealthy';
+}
+export function summariseProvisioning(desired, services) {
+    const running = [];
+    const failed = [];
+    const missing = [];
+    const seen = new Set();
+    for (const want of desired) {
+        seen.add(want.name);
+        const state = services[want.name];
+        if (!state) {
+            // The state that reads as success. Nothing tried, so nothing failed,
+            // so there is nothing in any list of problems.
+            missing.push({ name: want.name, image: want.image, status: 'missing', error: undefined });
+            continue;
+        }
+        (isUp(state) ? running : failed).push({
+            name: state.name,
+            image: state.image,
+            status: state.status,
+            error: state.error ?? (state.health === 'unhealthy' ? 'container reports unhealthy' : undefined),
+        });
+    }
+    // Services provisioned outside the declared set — omnitron's own Postgres
+    // is one — count against readiness when they are down. They were left out
+    // of this decision entirely, and a master with no control-plane database
+    // is not a healthy master.
+    for (const [name, state] of Object.entries(services)) {
+        if (seen.has(name))
+            continue;
+        (isUp(state) ? running : failed).push({
+            name: state.name ?? name,
+            image: state.image,
+            status: state.status,
+            error: state.error ?? (state.health === 'unhealthy' ? 'container reports unhealthy' : undefined),
+        });
+    }
+    const empty = desired.length === 0 && Object.keys(services).length === 0;
+    return {
+        ready: !empty && failed.length === 0 && missing.length === 0,
+        empty,
+        running,
+        failed,
+        missing,
+    };
+}
+/** One line saying what happened, for a log that has to be readable alone. */
+export function describeProvisioning(outcome) {
+    if (outcome.empty)
+        return 'Infrastructure: nothing is declared, so nothing was provisioned';
+    if (outcome.ready)
+        return `Infrastructure provisioned and healthy (${outcome.running.length} services)`;
+    const parts = [];
+    if (outcome.missing.length > 0)
+        parts.push(`${outcome.missing.length} missing (${outcome.missing.map((s) => s.name).join(', ')})`);
+    if (outcome.failed.length > 0)
+        parts.push(`${outcome.failed.length} not running (${outcome.failed.map((s) => s.name).join(', ')})`);
+    return `Infrastructure is NOT ready — ${parts.join('; ')}`;
+}
+/**
+ * The node's verdict on everything it was asked to bring up.
+ *
+ * Readiness counted the containers and the host services' REFUSALS, and not a
+ * host service that failed while its plan was carried out. Measured on the
+ * test node, 2026-09-23: bitcoind's start failed — `could not start bitcoind: `
+ * — and the node answered `ready: true` with «Infrastructure provisioned and
+ * healthy (5 services)», the failure sitting in `failed` beside it; the master
+ * logged that sentence and the deployment reported `6/6 apps online`.
+ */
+export function provisioningVerdict(outcome, hosted) {
+    if (hosted.failed.length === 0)
+        return { ready: outcome.ready, detail: describeProvisioning(outcome) };
+    const notUp = hosted.failed.map((f) => `${f.name} ${f.status}: ${f.error?.replace(/:\s*$/, '').trim() || 'no reason given'}`);
+    const containers = outcome.ready || outcome.empty ? '' : `${describeProvisioning(outcome)}; `;
+    return { ready: false, detail: `${containers}host services NOT up — ${notUp.join('; ')}` };
+}
+//# sourceMappingURL=provisioning-outcome.js.map

package/dist/infrastructure/provisioning-outcome.js.map

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

package/dist/infrastructure/server-registry.d.ts

@@ -2,15 +2,42 @@
  * ServerRegistry — Persistent registry for remote daemon servers
  *
  * Phase 5 implementation. Stores at ~/.omnitron/servers.json
+ *
+ * Read by `omnitron remote`, `omnitron fleet` and `omnitron deploy`. Note
+ * that this is NOT the registry the console's Nodes page and `omnitron node`
+ * use — those live in the SQLite `nodes` table via `NodeManagerService`. Two
+ * registries for "a remote machine" is a real gap, not a subtlety: a host
+ * added in the console is invisible to `omnitron deploy`, and one added with
+ * `omnitron remote add` never appears in the fleet view.
  */
 import type { ServerInfoDto } from '../shared/dto/services.js';
 export declare class ServerRegistry {
     private readonly registryFile;
     constructor();
+    /**
+     * Every registered server.
+     *
+     * A missing file means no servers have been registered; a file that cannot
+     * be read or parsed means something is wrong, and the two must not give the
+     * same answer. They did: one `catch` returned `[]` for both, so a truncated
+     * or half-written `servers.json` read as an empty fleet — and `deploy.ts`
+     * resolves its targets from this list, so a deploy to a corrupt registry
+     * targeted nothing and reported success.
+     *
+     * @throws when the file exists and cannot be read as a server list.
+     */
     list(): ServerInfoDto[];
     add(server: ServerInfoDto): void;
     remove(alias: string): boolean;
     get(alias: string): ServerInfoDto | undefined;
+    /**
+     * Write the list.
+     *
+     * Through a temporary file and a rename, which is atomic within a
+     * filesystem: a crash or a full disk part-way through leaves the previous
+     * registry intact rather than a truncated one. Writing in place meant every
+     * save had a window in which the file was neither the old list nor the new.
+     */
     private save;
 }
 //# sourceMappingURL=server-registry.d.ts.map

package/dist/infrastructure/server-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server-registry.d.ts","sourceRoot":"","sources":["../../src/infrastructure/server-registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;;IAMtC,IAAI,IAAI,aAAa,EAAE;IASvB,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAMhC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAQ9B,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI7C,OAAO,CAAC,IAAI;CAKb"}
+{"version":3,"file":"server-registry.d.ts","sourceRoot":"","sources":["../../src/infrastructure/server-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAE/D,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC,cAEC;IAED;;;;;;;;;;;OAWG;IACH,IAAI,IAAI,aAAa,EAAE,CAuBtB;IAED,GAAG,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAI/B;IAED,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAM7B;IAED,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE5C;IAED;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI;CAYb"}

package/dist/infrastructure/server-registry.js

@@ -2,6 +2,13 @@
  * ServerRegistry — Persistent registry for remote daemon servers
  *
  * Phase 5 implementation. Stores at ~/.omnitron/servers.json
+ *
+ * Read by `omnitron remote`, `omnitron fleet` and `omnitron deploy`. Note
+ * that this is NOT the registry the console's Nodes page and `omnitron node`
+ * use — those live in the SQLite `nodes` table via `NodeManagerService`. Two
+ * registries for "a remote machine" is a real gap, not a subtlety: a host
+ * added in the console is invisible to `omnitron deploy`, and one added with
+ * `omnitron remote add` never appears in the fleet view.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -11,14 +18,43 @@ export class ServerRegistry {
     constructor() {
         this.registryFile = path.join(OMNITRON_HOME, 'servers.json');
     }
+    /**
+     * Every registered server.
+     *
+     * A missing file means no servers have been registered; a file that cannot
+     * be read or parsed means something is wrong, and the two must not give the
+     * same answer. They did: one `catch` returned `[]` for both, so a truncated
+     * or half-written `servers.json` read as an empty fleet — and `deploy.ts`
+     * resolves its targets from this list, so a deploy to a corrupt registry
+     * targeted nothing and reported success.
+     *
+     * @throws when the file exists and cannot be read as a server list.
+     */
     list() {
+        let data;
+        try {
+            data = fs.readFileSync(this.registryFile, 'utf-8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return [];
+            throw new Error(`Cannot read the server registry at ${this.registryFile}: ${err.message}`, {
+                cause: err,
+            });
+        }
+        let parsed;
         try {
-            const data = fs.readFileSync(this.registryFile, 'utf-8');
-            return JSON.parse(data);
+            parsed = JSON.parse(data);
         }
-        catch {
-            return [];
+        catch (err) {
+            throw new Error(`The server registry at ${this.registryFile} is not valid JSON: ${err.message}`, {
+                cause: err,
+            });
         }
+        if (!Array.isArray(parsed)) {
+            throw new Error(`The server registry at ${this.registryFile} does not contain a list of servers.`);
+        }
+        return parsed;
     }
     add(server) {
         const servers = this.list().filter((s) => s.alias !== server.alias);
@@ -36,10 +72,29 @@ export class ServerRegistry {
     get(alias) {
         return this.list().find((s) => s.alias === alias);
     }
+    /**
+     * Write the list.
+     *
+     * Through a temporary file and a rename, which is atomic within a
+     * filesystem: a crash or a full disk part-way through leaves the previous
+     * registry intact rather than a truncated one. Writing in place meant every
+     * save had a window in which the file was neither the old list nor the new.
+     */
     save(servers) {
         const dir = path.dirname(this.registryFile);
         fs.mkdirSync(dir, { recursive: true });
-        fs.writeFileSync(this.registryFile, JSON.stringify(servers, null, 2), 'utf-8');
+        const tmp = `${this.registryFile}.${process.pid}.tmp`;
+        try {
+            fs.writeFileSync(tmp, JSON.stringify(servers, null, 2), { encoding: 'utf-8', mode: 0o600 });
+            fs.renameSync(tmp, this.registryFile);
+        }
+        catch (err) {
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { /* nothing to clean up */ }
+            throw err;
+        }
     }
 }
 //# sourceMappingURL=server-registry.js.map

package/dist/infrastructure/server-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"server-registry.js","sourceRoot":"","sources":["../../src/infrastructure/server-registry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGtD,MAAM,OAAO,cAAc;IACR,YAAY,CAAS;IAEtC;QACE,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,EAAE,cAAc,CAAC,CAAC;IAC/D,CAAC;IAED,IAAI;QACF,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YACzD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAoB,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,GAAG,CAAC,MAAqB;QACvB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,KAAa;QAClB,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;QAC1D,IAAI,QAAQ,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACrD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,KAAa;QACf,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,KAAK,CAAC,CAAC;IACpD,CAAC;IAEO,IAAI,CAAC,OAAwB;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;QAC5C,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACvC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IACjF,CAAC;CACF"}
+{"version":3,"file":"server-registry.js","sourceRoot":"","sources":["../../src/infrastructure/server-registry.ts"],"names":[],"mappings":"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"}

package/dist/infrastructure/service-binding.d.ts

@@ -0,0 +1,60 @@
+/**
+ * How a stack runs a service an application declares: where, on which
+ * network, on which ports, with which credentials.
+ *
+ * Three readers answered this each for itself — the node's container
+ * resolver, its bare-metal planner, and the master's resolver of the
+ * applications' environment — and their answers had drifted apart on the
+ * one service where being wrong costs money. Measured against the test
+ * stack, which runs Bitcoin on mainnet (2026-09-23):
+ *
+ *   - nothing chose between a declaration's `docker` and `bareMetal` blocks:
+ *     a node given the service would make the container AND plan the unit;
+ *   - the bare-metal templates took their credentials from the
+ *     application's declaration — `omni_regtest` / `omni_regtest_dev_password`,
+ *     in git — whatever network the stack ran;
+ *   - the applications' environment for a service provisioned on the node
+ *     read the same declaration: the regtest port and the regtest password,
+ *     beside `BITCOIN_NETWORK=mainnet`.
+ *
+ * One answer now, and one rule for credentials: an application's own
+ * `secrets` belong to the network it declares — a laptop's. A stack that
+ * runs another network gives its own (`serviceOverrides.<name>.secrets`,
+ * vault references), and a credential it does not give is missing, not
+ * borrowed from the laptop.
+ */
+import type { IServiceOverride, IServiceRequirement, SecretRef } from './types.js';
+export type Provisioning = 'external' | 'docker' | 'bareMetal' | 'disabled' | 'none';
+export interface ServiceBinding {
+    /**
+     * `none` is a service with nothing to provision it by: no docker block,
+     * no bare-metal block, and no address to reach it at.
+     */
+    provisioning: Provisioning;
+    networkMode: string | undefined;
+    /** False when the stack runs another network than the declaration names. */
+    declaredNetwork: boolean;
+    ports: Record<string, number>;
+    /** References until the master resolves them; values after. */
+    secrets: Record<string, string | SecretRef>;
+    /** Where an `external` service is. */
+    host?: string | undefined;
+}
+/** What of a declaration the binding reads. */
+type Requirement = {
+    networkMode?: string | undefined;
+    secrets?: IServiceRequirement['secrets'] | undefined;
+    ports?: Record<string, number> | undefined;
+    docker?: unknown;
+    bareMetal?: unknown;
+};
+export declare function bindService(requirement: Requirement, override?: IServiceOverride | undefined): ServiceBinding;
+/**
+ * The credentials that are values. A reference still standing — the master
+ * did not resolve it, or the vault did not hold it — is left out, so a
+ * template needing it reports it unfilled rather than writing
+ * `[object Object]` into a config file.
+ */
+export declare function secretValues(binding: Pick<ServiceBinding, 'secrets'>): Record<string, string>;
+export {};
+//# sourceMappingURL=service-binding.d.ts.map

package/dist/infrastructure/service-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-binding.d.ts","sourceRoot":"","sources":["../../src/infrastructure/service-binding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEnF,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;AAErF,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;IAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,4EAA4E;IAC5E,eAAe,EAAE,OAAO,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC5C,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,+CAA+C;AAC/C,KAAK,WAAW,GAAG;IACjB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,OAAO,CAAC,EAAE,mBAAmB,CAAC,SAAS,CAAC,GAAG,SAAS,CAAC;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,CAAC;AAEF,wBAAgB,WAAW,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,EAAE,gBAAgB,GAAG,SAAS,GAAG,cAAc,CAoC7G;AAyBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAM7F"}