@omnitron-dev/omnitron 0.1.3 → 0.3.0

package/dist/database/sqlite-date-binding.js

@@ -0,0 +1,174 @@
+/**
+ * Let a SQLite-backed Kysely accept the `Date` values the rest of the code
+ * passes it.
+ *
+ * `better-sqlite3` binds "numbers, strings, bigints, buffers, and null" and
+ * refuses everything else, a `Date` included. Postgres's driver serialises
+ * one happily. The daemon runs the SAME services against both — a master on
+ * Postgres, a slave on SQLite — so any query written with a `Date` works on
+ * one and throws on the other, and the schema types describe the master.
+ *
+ * Measured 2026-09-14 on a provisioned slave node:
+ *
+ *     ERROR  Log retention pass failed
+ *       error: "SQLite3 can only bind numbers, strings, bigints, buffers, and null"
+ *     WARN   Sync buffer retention pass failed
+ *       error: "SQLite3 can only bind numbers, strings, bigints, buffers, and null"
+ *
+ * — the second one every thirty seconds, with the buffer bound bounding
+ * nothing. Both had been unreachable until this week: the slave replication
+ * path had no producer, and the bound only ran at the end of a successful
+ * cycle. Making them run is what made them fail.
+ *
+ * Converting at the two call sites was the obvious fix and the wrong one:
+ * there are two today because there are two features, and the next query
+ * written against a slave's storage with a `Date` in it fails the same way.
+ * The driver is where the value has to be right, so the conversion goes
+ * there.
+ *
+ * ISO-8601 is what these columns hold, and it sorts chronologically as text —
+ * which is why the comparisons this fixes are correct once the bind works.
+ */
+/**
+ * Replace every `Date` in a statement's arguments with its ISO form.
+ *
+ * better-sqlite3 accepts bindings two ways — `stmt.all(a, b)` and
+ * `stmt.all([a, b])` — and Kysely's SQLite driver uses the SECOND:
+ *
+ *     rows: stmt.all(parameters)
+ *     const { changes } = stmt.run(parameters)
+ *
+ * So this is handed ONE argument which is the array of bindings, and a
+ * version that looked only at the top level found no Date and changed
+ * nothing.
+ *
+ * That is exactly what happened. The first fix converted the spread form,
+ * its test called it the spread way, both were green, and the failure it was
+ * written for went on every thirty seconds on a real node — visible only
+ * because the node was watched after the version shipped:
+ *
+ *     05:53:02  Sync buffer retention pass failed
+ *     05:53:32  Sync buffer retention pass failed   ← on the FIXED build
+ *
+ * A test that calls the code differently from its only caller tests a
+ * different thing.
+ */
+export function serialiseDates(args) {
+    let changed = false;
+    // A boolean the same way and for the same reason: better-sqlite3 refuses it,
+    // and the node's alert engine asks `enabled = true` (2026-09-30, the first
+    // service that runs on both roles with a boolean in a query). SQLite keeps
+    // booleans as 0 / 1.
+    const convert = (value) => {
+        if (value instanceof Date) {
+            changed = true;
+            return value.toISOString();
+        }
+        if (typeof value === 'boolean') {
+            changed = true;
+            return value ? 1 : 0;
+        }
+        // One level of nesting, because that is the shape a driver passes: an
+        // array OF bindings. Deeper is not a thing SQLite binds, and walking
+        // arbitrary structures would convert Dates inside a JSON column's value,
+        // which the caller serialised deliberately.
+        if (Array.isArray(value)) {
+            let innerChanged = false;
+            const inner = value.map((v) => {
+                if (v instanceof Date) {
+                    innerChanged = true;
+                    return v.toISOString();
+                }
+                if (typeof v === 'boolean') {
+                    innerChanged = true;
+                    return v ? 1 : 0;
+                }
+                return v;
+            });
+            if (innerChanged) {
+                changed = true;
+                return inner;
+            }
+            return value;
+        }
+        return value;
+    };
+    const out = args.map(convert);
+    return changed ? out : args;
+}
+/**
+ * Wrap a better-sqlite3 database so every bound `Date` becomes a string.
+ *
+ * Done at the driver rather than as a Kysely plugin because a plugin's
+ * `transformQuery` sees the query AST, where a parameter is a
+ * `ValueNode` — reachable, but only by walking every node type Kysely can
+ * produce, and silently incomplete the moment it produces a new one. The
+ * driver sees the finished parameter list, which is the whole of what is
+ * being bound and cannot be partially traversed.
+ */
+export function withDateBinding(database) {
+    const originalPrepare = database.prepare.bind(database);
+    database.prepare = (sql) => {
+        const statement = originalPrepare(sql);
+        for (const method of ['run', 'get', 'all', 'iterate']) {
+            const original = statement[method];
+            if (typeof original !== 'function')
+                continue;
+            statement[method] = function wrapped(...parameters) {
+                return original.apply(this, [...serialiseDates(parameters)]);
+            };
+        }
+        return statement;
+    };
+    return database;
+}
+/**
+ * Read a stored timestamp back as ISO-8601 UTC.
+ *
+ * The binding above is only half of this boundary. SQLite has no date type,
+ * so a column holds whatever spelling wrote it — and on a slave that is two
+ * spellings in one table:
+ *
+ *     createdAt   2026-09-15 06:01:37          ← DEFAULT (datetime('now'))
+ *     syncedAt    2026-09-15T06:01:37.123Z     ← a bound Date, through serialiseDates
+ *
+ * `datetime('now')` is UTC and says so nowhere. The slave ships `createdAt`
+ * to the master exactly as stored, and the master inserts it into a
+ * `timestamptz` column — where Postgres resolves a timestamp with no offset
+ * in the session's TimeZone. That is UTC on the image we run, so today the
+ * value survives the trip. Measured on omnitron-pg 2026-09-15:
+ *
+ *     SET TimeZone='Europe/Moscow';
+ *     SELECT '2026-09-15T06:01:37.000Z'::timestamptz - '2026-09-15 06:01:37'::timestamptz;
+ *     → 03:00:00
+ *
+ * Every replicated metric, log line, alert and span moves by that much, and
+ * nothing in omnitron pins the master's TimeZone. A timestamp crossing a
+ * machine boundary must carry its zone; this is the last point on the slave
+ * that can put it back.
+ *
+ * A value that cannot be read as a time is returned unchanged rather than
+ * replaced by a plausible one — a wrong timestamp is worse than an obviously
+ * broken one, because only the second gets looked at.
+ */
+const NAIVE_TIMESTAMP = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}:\d{2}(?:\.\d+)?)$/;
+export function toIsoUtc(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? String(value) : value.toISOString();
+    }
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return new Date(value).toISOString();
+    }
+    const text = String(value ?? '').trim();
+    // No offset in the text: SQLite's own `datetime('now')` shape, which is
+    // UTC. Said explicitly, because `new Date('2026-09-15 06:01:37')` reads it
+    // as LOCAL time — the same three-hour error, moved into this process.
+    const naive = NAIVE_TIMESTAMP.exec(text);
+    if (naive) {
+        const parsed = new Date(`${naive[1]}T${naive[2]}Z`);
+        return Number.isNaN(parsed.getTime()) ? text : parsed.toISOString();
+    }
+    const parsed = new Date(text);
+    return Number.isNaN(parsed.getTime()) ? text : parsed.toISOString();
+}
+//# sourceMappingURL=sqlite-date-binding.js.map

package/dist/database/sqlite-date-binding.js.map

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

package/dist/execution/data-channel.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A command's stdout as DATA, past the transport's masker.
+ *
+ * Every result the execution engine (xec) returns has passed through its
+ * sensitive-data masker: stdout, stderr and the command, for display. That
+ * is right for a message and wrong for data. A holder record of a node's
+ * deploy lease, `{"token":"<uuid>",…}`, came back as `"token": [REDACTED]` —
+ * no longer JSON — on EVERY read, so a refused deployment could never say who
+ * held the node. An attestation line whose probe output said `password=…`
+ * was cut through its closing quote and refused as «printed no JSON», or
+ * edited and stored as evidence. And the first operator account made on
+ * daos/test (2026-09-23) arrived as `"password": [REDACTED]` and was lost.
+ *
+ * The engine has no switch for one call — masking is set per adapter, and
+ * turning it off around a call would unmask whatever else runs meanwhile.
+ * So the data is carried in a form no rule can match: the node hex-encodes
+ * the command's stdout and this side decodes it. Every rule the masker has
+ * needs a character outside `[0-9a-f]` — `:` or `=` after a key, `_` or a
+ * letter past `f` in a token prefix, `://`, `-----BEGIN` — which is a
+ * property of today's rules, not a law: the court that holds this sends a
+ * payload carrying every trigger through the real engine and requires it
+ * back byte for byte, and a rule that learns long hex strings turns it red.
+ * If the channel ever does come back rewritten, it does not decode, and that
+ * is said — never read as data.
+ *
+ * Stderr is not touched: it is words, and stays masked.
+ *
+ * Use it where stdout is data a caller parses or stores, and name the caller:
+ * what comes out of it is unmasked, and a log line that printed it whole
+ * would be the masker's bypass.
+ */
+/**
+ * The command, run by `sh`, its stdout hex-encoded on the way out and its own
+ * exit code kept — `od`'s would say the encoding worked, not that the command
+ * did. `-v`: without it `od` folds repeated lines into `*`. Command
+ * substitution drops trailing newlines, which no reader of these outputs
+ * depends on.
+ */
+export declare function throughDataChannel(command: string): string;
+/** The stdout the command printed, or why the channel cannot be read. */
+export declare function fromDataChannel(stdout: string): {
+    readonly ok: true;
+    readonly text: string;
+} | {
+    readonly ok: false;
+    readonly because: string;
+};
+//# sourceMappingURL=data-channel.d.ts.map

package/dist/execution/data-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-channel.d.ts","sourceRoot":"","sources":["../../src/execution/data-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAU/I"}

package/dist/execution/data-channel.js

@@ -0,0 +1,55 @@
+/**
+ * A command's stdout as DATA, past the transport's masker.
+ *
+ * Every result the execution engine (xec) returns has passed through its
+ * sensitive-data masker: stdout, stderr and the command, for display. That
+ * is right for a message and wrong for data. A holder record of a node's
+ * deploy lease, `{"token":"<uuid>",…}`, came back as `"token": [REDACTED]` —
+ * no longer JSON — on EVERY read, so a refused deployment could never say who
+ * held the node. An attestation line whose probe output said `password=…`
+ * was cut through its closing quote and refused as «printed no JSON», or
+ * edited and stored as evidence. And the first operator account made on
+ * daos/test (2026-09-23) arrived as `"password": [REDACTED]` and was lost.
+ *
+ * The engine has no switch for one call — masking is set per adapter, and
+ * turning it off around a call would unmask whatever else runs meanwhile.
+ * So the data is carried in a form no rule can match: the node hex-encodes
+ * the command's stdout and this side decodes it. Every rule the masker has
+ * needs a character outside `[0-9a-f]` — `:` or `=` after a key, `_` or a
+ * letter past `f` in a token prefix, `://`, `-----BEGIN` — which is a
+ * property of today's rules, not a law: the court that holds this sends a
+ * payload carrying every trigger through the real engine and requires it
+ * back byte for byte, and a rule that learns long hex strings turns it red.
+ * If the channel ever does come back rewritten, it does not decode, and that
+ * is said — never read as data.
+ *
+ * Stderr is not touched: it is words, and stays masked.
+ *
+ * Use it where stdout is data a caller parses or stores, and name the caller:
+ * what comes out of it is unmasked, and a log line that printed it whole
+ * would be the masker's bypass.
+ */
+import { shellEscape } from '../shared/shell-escape.js';
+/**
+ * The command, run by `sh`, its stdout hex-encoded on the way out and its own
+ * exit code kept — `od`'s would say the encoding worked, not that the command
+ * did. `-v`: without it `od` folds repeated lines into `*`. Command
+ * substitution drops trailing newlines, which no reader of these outputs
+ * depends on.
+ */
+export function throughDataChannel(command) {
+    return `out=$(sh -c ${shellEscape(command)}); code=$?; printf '%s' "$out" | od -An -v -tx1 | tr -d ' \\n'; exit $code`;
+}
+/** The stdout the command printed, or why the channel cannot be read. */
+export function fromDataChannel(stdout) {
+    const hex = stdout.trim();
+    if (/^(?:[0-9a-f]{2})*$/.test(hex))
+        return { ok: true, text: Buffer.from(hex, 'hex').toString('utf8') };
+    const stray = hex.replace(/[0-9a-f]/g, '').length;
+    return {
+        ok: false,
+        because: `the data channel came back as something other than its encoding (${hex.length} characters, ${stray} of them not hex` +
+            `${hex.length % 2 === 1 ? ', odd length' : ''}) — rewritten or cut on the way; it was not read as data`,
+    };
+}
+//# sourceMappingURL=data-channel.js.map

package/dist/execution/data-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-channel.js","sourceRoot":"","sources":["../../src/execution/data-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,OAAO,eAAe,WAAW,CAAC,OAAO,CAAC,4EAA4E,CAAC;AACzH,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,eAAe,CAAC,MAAc;IAC5C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IAC1B,IAAI,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;IACxG,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC;IAClD,OAAO;QACL,EAAE,EAAE,KAAK;QACT,OAAO,EACL,oEAAoE,GAAG,CAAC,MAAM,gBAAgB,KAAK,kBAAkB;YACrH,GAAG,GAAG,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,0DAA0D;KAC1G,CAAC;AACJ,CAAC"}

package/dist/execution/execution.service.d.ts

@@ -37,6 +37,93 @@ export interface ExecOptions {
     /** Suppress stderr in logs */
     quiet?: boolean;
 }
+/**
+ * Render the `command:error` reason.
+ *
+ * The contract says `string`, and the fallbacks are for the version that
+ * does not: an engine that starts passing the Error itself must not silently
+ * turn this log line back into `[object Object]`.
+ */
+export declare function describeXecError(error: unknown): string;
+/**
+ * One SSH connection config, with a budget a control plane can meet.
+ *
+ * ssh2's `readyTimeout` defaults to 20 seconds, and a handshake is
+ * arithmetic performed in JavaScript — on the same event loop the daemon
+ * uses to supervise processes and reconcile containers. Twenty seconds is a
+ * generous budget for an idle process and a tight one for a busy daemon.
+ *
+ * Measured: `omnitron fleet upgrade` from a daemon that was starting six
+ * applications failed with `Timed out while waiting for handshake`, against
+ * a node whose load average was 0.02, which accepted a connection from the
+ * CLI seconds later, and whose sshd logged no refusal. The node was idle;
+ * the handshake never got the CPU.
+ *
+ * The keepalives are for the other end of the same problem: a tunnel the
+ * mesh holds open for hours across a link that drops idle connections. Four
+ * missed probes at fifteen seconds is a minute of silence before the socket
+ * is called dead, which is longer than any pause the event loop has been
+ * measured to take.
+ *
+ * Written once because it was written three times: `ssh`, `tunnel` and
+ * `uploadFile` each built this object, and a change to any of them would
+ * have reached one of the three.
+ */
+/**
+ * How long a pooled SSH connection may sit without a command run on it.
+ *
+ * The mesh reaches a node whose daemon port is closed through an in-process
+ * SSH tunnel (`tunnel()` below, `mesh-link.ts`). That connection is never
+ * idle — netron heartbeats cross it every 15 s — but `@xec-sh/core` counts
+ * USE as command execution, and a forwarded channel is not a command. Its
+ * pool sweeps every 60 s and closes anything whose `lastUsed` is older than
+ * `idleTimeout`, which defaults to 300 s. Sweeps land at 60, 120 … 300
+ * (300 is not greater than 300, so it survives) and 360, where it closes.
+ *
+ * Measured on `daos/test`, 2026-09-22: 51 mesh drops in a day, «Socket
+ * closed during RPC», median interval between them 360 s with 32 of 45
+ * inside 360 ± 5, each followed by a rejoin about nine seconds later. An
+ * interval that precise is a timer, and this is the timer.
+ *
+ * So idleness is switched off as a reason to close: not because these
+ * connections are precious, but because the pool cannot measure it for the
+ * one that matters. What it CAN measure it still does — its own
+ * `isConnected()` pass reaps a connection that actually died, and this does
+ * not touch that.
+ *
+ * The two numbers do not mean the same thing, which is the trap here.
+ * `maxLifetime` is guarded by `maxLifetime > 0`, so zero disables it.
+ * `idleTimeout` has no such guard — `now - lastUsed > idleTimeout` — so zero
+ * would close every connection on the very next sweep, the exact opposite.
+ * The way to say «never» with this API is a number nothing can exceed.
+ *
+ * A first attempt used a day, and the test for it said so: the sweep at
+ * 24 h + 60 s still closes the link. That would have moved the drop from
+ * every six minutes to once a day and called it fixed.
+ */
+export declare const SSH_CONNECTION_POOL: {
+    readonly idleTimeout: number;
+    readonly maxLifetime: 0;
+};
+/**
+ * How long one file transfer may take: a minute to open it, and the bytes at
+ * no less than 32 KiB/s.
+ *
+ * A transfer had no bound at all, and on 2026-09-24 three of them never
+ * ended: `daos/test` stood «delivering 6 artifact(s)» for 19 minutes, holding
+ * the node's deploy lease, until the master was restarted. The chain is in
+ * `@xec-sh/core`: every channel to a node rides ONE pooled SSH connection, a
+ * command that timed out behind the transfers made the pool close that
+ * connection with a graceful `end()` — which stops ssh2's keepalive — and a
+ * transfer still running on it got neither an error nor an end. New commands
+ * opened a new connection and worked; the transfers on the old one waited
+ * forever. Only a deadline of our own ends them.
+ *
+ * The floor is generous on purpose — measured the day after, 26 MB of
+ * artifacts crossed in ~70 s, about 0.4 MB/s — so a slow link still delivers,
+ * and a dead one fails in minutes, with its words, instead of never.
+ */
+export declare function uploadDeadlineMs(bytes: number): number;
 export declare class ExecutionService {
     private readonly logger;
     private engine;
@@ -54,7 +141,59 @@ export declare class ExecutionService {
     /**
      * Execute command on a remote host via SSH.
      */
+    /**
+     * A local port that speaks to `remotePort` on the target, over SSH.
+     *
+     * The master reaches a node's daemon on its TCP port. A node whose firewall
+     * allows only SSH — which is the normal posture for a machine on the public
+     * internet, and what the first provisioned node turned out to have — is
+     * then unreachable, and the mesh it is supposed to join cannot form. The
+     * symptom is silence: the node answers SSH, deploys fine, reports healthy,
+     * and replicates nothing.
+     *
+     * Measured on that node: `ss -ltn` shows the daemon on `0.0.0.0:9700`, and
+     * `ufw status` allows 22/tcp and three ports from one private address. A
+     * direct connection times out; through this, the same daemon answers.
+     *
+     * Opening the port on the node would be the other fix, and it is worse: it
+     * asks every operator to widen a firewall for a control plane that already
+     * holds SSH credentials for the machine. Whoever can open this tunnel can
+     * already run commands there.
+     *
+     * The caller owns the returned handle and must `close()` it — each one
+     * holds an SSH connection.
+     */
+    tunnel(target: SSHTarget, remotePort: number, options?: {
+        remoteHost?: string;
+        localHost?: string;
+    }): Promise<{
+        host: string;
+        port: number;
+        close(): Promise<void>;
+    }>;
     ssh(target: SSHTarget, command: string, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Copy a local file to a remote host over the SSH connection.
+     *
+     * Here rather than in the caller because this class owns the engine, and
+     * because the alternative already existed and could not work: deployment
+     * shelled out to `scp`, which — like the `ssh -o BatchMode=yes` beside it —
+     * can offer a key file and nothing else. The console collects passwords and
+     * key passphrases and keeps them in the daemon's vault, so every node
+     * registered that way was untransferable-to by construction.
+     *
+     * The engine speaks SFTP over the same authenticated connection as
+     * `ssh()`, so one credential path serves both.
+     */
+    uploadFile(target: SSHTarget, localPath: string, remotePath: string): Promise<void>;
+    /** Transfers still to finish, per node — see `uploadFile`. */
+    private transfersByNode?;
+    private transferOnce;
+    /**
+     * `work`, or a rejection once `ms` have passed. The work itself is not
+     * stopped — nothing in the engine can stop it — only no longer waited for.
+     */
+    private withinDeadline;
     /**
      * Execute command inside a Docker container.
      */

package/dist/execution/execution.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execution.service.d.ts","sourceRoot":"","sources":["../../src/execution/execution.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AAMjE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAMD,qBAAa,gBAAgB;IAIf,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,WAAW,CAAS;gBAEC,MAAM,EAAE,OAAO;IAE5C;;;OAGG;YACW,SAAS;IAuCvB;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAkCvE;;OAEG;IACG,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAwCzF;;OAEG;IACG,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ/F;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B;;OAEG;IACH,WAAW,IAAI,OAAO;YAQR,YAAY;CA4B3B"}
+{"version":3,"file":"execution.service.d.ts","sourceRoot":"","sources":["../../src/execution/execution.service.ts"],"names":[],"mappings":"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"}