@omnitron-dev/omnitron 0.2.0 → 0.3.1

package/dist/services/sync-policy.js

@@ -0,0 +1,161 @@
+/**
+ * The decisions the slave→master replication makes, separated from the
+ * database calls that carry them out.
+ *
+ * `sync.service.ts` opens with five numbered guarantees. Four of them were
+ * not implemented, and each failure is silent by construction — replication
+ * that drops data still reports success, because the thing that would have
+ * noticed is the thing that is missing.
+ *
+ *   1. "Zero data loss"  The push path marked every entry synced after
+ *      `receiveBatch` returned, and `receiveBatch` swallows per-entry
+ *      ingestion failures into a warning. Forty rejected entries out of a
+ *      hundred were marked delivered and evicted twenty-four hours later.
+ *
+ *      The pull path was worse: `drainBuffer` marked entries synced *before*
+ *      returning them, so a response lost in transit, a checksum mismatch or
+ *      a rate-limit rejection lost the data outright — and the caller logged
+ *      the failure at debug level.
+ *
+ *   4. "Idempotent (safe to retry)"  There was no mechanism. `batchId` was
+ *      generated, transmitted, and used only inside log and error strings.
+ *      Retrying meant ingesting twice.
+ *
+ *   5. "Bounded buffer — oldest entries evicted when maxBufferSize reached"
+ *      `maxBufferSize` was read from config, defaulted to 500 MB, and never
+ *      referenced again. A slave that lost its master buffered until the
+ *      disk filled.
+ *
+ * The three are entangled: making delivery honest (1) means entries are
+ * retried, which requires deduplication (4) or the loss becomes duplication;
+ * and retaining undelivered entries makes the unbounded buffer (5) reachable
+ * rather than theoretical. They are fixed together or not at all.
+ */
+/**
+ * Which entries the slave may release.
+ *
+ * A duplicate counts as delivered: the master has it. A transient failure
+ * does not, however many times it has been attempted — data the master
+ * rejected because it was momentarily unable is still data the slave holds,
+ * and dropping it here is the loss that guarantee 1 forbids.
+ *
+ * A DISCARD is different, and it is released. The master has said this entry
+ * can never be stored — a malformed uuid, a foreign key it does not have —
+ * and answered the same way for every attempt. Holding it does not preserve
+ * it: it parks it at the head of the buffer with everything behind it
+ * waiting, until the bound above eventually drops the lot. Releasing the one
+ * entry the master named, loudly, costs that entry and saves the rest.
+ */
+export function deliveredIds(outcome) {
+    return [...outcome.accepted, ...outcome.duplicates, ...outcome.discarded];
+}
+/**
+ * Should a pull sweep stop?
+ *
+ * `drainBuffer` no longer marks entries synced, so an entry the master keeps
+ * rejecting comes back on the next fetch. Without this the sweep would
+ * re-fetch and re-reject the same page forever.
+ *
+ * Returns true when the batch contains nothing the sweep has not already
+ * seen — that is, when continuing cannot make progress.
+ */
+export function sweepMadeProgress(seen, batchIds) {
+    return batchIds.some((id) => !seen.has(id));
+}
+/** Synced entries are kept this long for debugging before routine eviction. */
+export const SYNCED_RETENTION_MS = 24 * 60 * 60 * 1000;
+/**
+ * How much to remove from the WAL.
+ *
+ * Routine eviction of old synced rows happens every cycle. The overflow pass
+ * runs only when the table is over budget, and it is estimated rather than
+ * exact: rows are deleted oldest-first until the projected size fits, using
+ * the table's own average row size. An estimate is the right instrument here
+ * — the alternative to deleting approximately enough is a full disk.
+ *
+ * `discardsUndelivered` is the caller's cue to log at warning level. Dropping
+ * undelivered data is correct when the disk is the alternative, and it is
+ * never something to do quietly.
+ */
+export function planEviction(params) {
+    const { totalBytes, maxBytes, totalRows, syncedRows } = params;
+    const plan = {
+        syncedOlderThanMs: SYNCED_RETENTION_MS,
+        overflowRows: 0,
+        discardsUndelivered: false,
+    };
+    if (!(totalBytes > maxBytes) || totalRows <= 0 || maxBytes <= 0)
+        return plan;
+    const bytesPerRow = totalBytes / totalRows;
+    if (!(bytesPerRow > 0))
+        return plan;
+    // Target 90% of the budget so the next cycle is not immediately over
+    // again — evicting exactly to the line means evicting every cycle.
+    const targetBytes = maxBytes * 0.9;
+    const rowsToDrop = Math.ceil((totalBytes - targetBytes) / bytesPerRow);
+    plan.overflowRows = Math.min(rowsToDrop, totalRows);
+    plan.discardsUndelivered = plan.overflowRows > syncedRows;
+    return plan;
+}
+/** Postgres classes 22 (data exception) and 23 (integrity violation). */
+const PERMANENT_PG_PREFIXES = ['22', '23'];
+/** better-sqlite3 spells the same thing differently. */
+const PERMANENT_SQLITE = /^SQLITE_(CONSTRAINT|MISMATCH)/;
+export function classifyIngestFailure(err) {
+    const code = err?.code;
+    if (typeof code === 'string') {
+        if (PERMANENT_SQLITE.test(code))
+            return 'permanent';
+        // Postgres SQLSTATE is five characters; the first two are the class.
+        if (/^[0-9A-Z]{5}$/.test(code) && PERMANENT_PG_PREFIXES.includes(code.slice(0, 2))) {
+            return 'permanent';
+        }
+    }
+    // A driver that reports no code at all still says this much in its text,
+    // and the two that matter here are the ones a malformed payload produces.
+    const message = err?.message;
+    if (typeof message === 'string' && /invalid input syntax|violates (foreign key|not-null|check) constraint/i.test(message)) {
+        return 'permanent';
+    }
+    return 'transient';
+}
+// =============================================================================
+// How long the master remembers what it took
+// =============================================================================
+/**
+ * The dedup window: how long `sync_ingested` keeps a claim, in days.
+ *
+ * The ledger exists so that an entry offered twice is taken once, and an
+ * entry is offered again only while its node still holds it unacknowledged.
+ * Since a pull runs one at a time per connection (`pullSyncData`), at most
+ * ONE batch per node is ever claimed and not yet acknowledged: the batch in
+ * flight when the connection dropped between the claim and the ack. The
+ * window has to outlast that node's absence; when it does not, the price is
+ * bounded — at most one batch of telemetry stored twice.
+ *
+ * The ledger kept every claim instead. On the master, 2026-09-22: 9 934 304
+ * rows and 2.2 GB, growing by ~3.3 million a day per node at 38 entries a
+ * second, with an index on `ingestedAt` created «for pruning» and no pruner.
+ * Each day of window costs one such day of rows, so one day it is.
+ *
+ * The window also caps an open defect in the key. A node whose `slave.db` is
+ * recreated restarts its AUTOINCREMENT ids, and a new entry is read as a
+ * duplicate when its id is still claimed. Inside a window of one day that is
+ * only an id the node used in the last day — none at all for a node older
+ * than that, whose recent ids are its highest — instead of every id since the
+ * node first connected. The cure for the key itself is an epoch in it, which
+ * is a change to the protocol between versions.
+ */
+export const LEDGER_WINDOW_DAYS = 1;
+/**
+ * When the ledger is pruned. The same cadence as the log table's retention
+ * (`log-collector.service.ts`), for the same reasons: not at the instant the
+ * daemon starts, when the migrations that create the table may still be
+ * running; hourly after that; and a minute apart while a pass keeps hitting
+ * its ceiling, so the backlog of a ledger that was never pruned drains in
+ * minutes with every statement still bounded.
+ */
+export const LEDGER_FIRST_PASS_DELAY_MS = 60_000;
+export const LEDGER_INTERVAL_MS = 60 * 60 * 1_000;
+export const LEDGER_BACKLOG_INTERVAL_MS = 60 * 1_000;
+//# sourceMappingURL=sync-policy.js.map

package/dist/services/sync-policy.js.map

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

package/dist/services/sync-summary.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The sync figures a stack reports.
+ *
+ * Two of the three used to be literals:
+ *
+ *     syncedSlaves: 0,
+ *     totalPending: 0,
+ *
+ * sitting beside a `totalSlaves` that was counted, in one object, with the
+ * same shape — so a reader had no way to tell the measurement from the
+ * assertion. «0 pending» reads as «replication is up to date», and it said
+ * that whether replication was up to date, stopped, or had never started.
+ *
+ * The data was there the whole time: `OmnitronSync.getSyncStatus` answers per
+ * node, and `getNodeSyncStatus` already calls it. What that call sees is the
+ * diagnosis — `pendingItems` climbing while `lastSyncAt` stands still — and
+ * the cost of not seeing it is recorded in that method: 47,407 entries
+ * buffered on one node, none delivered, over eleven hours, while the page
+ * reported it healthy.
+ *
+ * Which decides the one real question here: what a node we have NOT heard
+ * from contributes. Nothing. It is not synced, and its backlog is unknown
+ * rather than zero — the same mistake as the literal, made a level down.
+ */
+import type { ISyncStatus } from '../shared/dto/project.js';
+export interface SyncSummary {
+    /** Nodes that are not the master. Counted from the stack's own roster. */
+    totalSlaves: number;
+    /** Slaves connected with nothing waiting. Silence does not count as synced. */
+    syncedSlaves: number;
+    /** Entries waiting across the slaves we have a status for. */
+    totalPending: number;
+}
+export interface NodeWithSync {
+    role?: string | undefined;
+    syncStatus?: ISyncStatus | null | undefined;
+}
+export declare function summariseSync(nodes: readonly NodeWithSync[]): SyncSummary;
+//# sourceMappingURL=sync-summary.d.ts.map

package/dist/services/sync-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-summary.d.ts","sourceRoot":"","sources":["../../src/services/sync-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,MAAM,WAAW,WAAW;IAC1B,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,UAAU,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7C;AAwBD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,WAAW,CAiBzE"}

package/dist/services/sync-summary.js

@@ -0,0 +1,62 @@
+/**
+ * The sync figures a stack reports.
+ *
+ * Two of the three used to be literals:
+ *
+ *     syncedSlaves: 0,
+ *     totalPending: 0,
+ *
+ * sitting beside a `totalSlaves` that was counted, in one object, with the
+ * same shape — so a reader had no way to tell the measurement from the
+ * assertion. «0 pending» reads as «replication is up to date», and it said
+ * that whether replication was up to date, stopped, or had never started.
+ *
+ * The data was there the whole time: `OmnitronSync.getSyncStatus` answers per
+ * node, and `getNodeSyncStatus` already calls it. What that call sees is the
+ * diagnosis — `pendingItems` climbing while `lastSyncAt` stands still — and
+ * the cost of not seeing it is recorded in that method: 47,407 entries
+ * buffered on one node, none delivered, over eleven hours, while the page
+ * reported it healthy.
+ *
+ * Which decides the one real question here: what a node we have NOT heard
+ * from contributes. Nothing. It is not synced, and its backlog is unknown
+ * rather than zero — the same mistake as the literal, made a level down.
+ */
+/**
+ * A node is synced when it has nothing left to deliver.
+ *
+ * NOT `connected && pendingItems === 0`, which is what this said first and
+ * which can never be true. `ISyncStatus.connected` is `masterInvoke !==
+ * null` — whether the slave holds a PUSH channel to the master — and that
+ * channel has no production caller; `sync.rpc-service.ts` says so in as many
+ * words. Replication runs the other way: the master PULLS, through
+ * `drainBuffer`/`ackDrained`, and `ackDrained` is what advances
+ * `lastSyncAt`. So a node that is perfectly up to date reports
+ * `connected: false`, and requiring it made «synced» a state the column
+ * could never print — an unreachable figure one level down from the literal
+ * zero it replaced.
+ *
+ * Of the six fields, three are written only by that dead path — `connected`,
+ * `lastError` and `failedAttempts`. `pendingItems` and `lastSyncAt` are the
+ * two the pull path maintains, and they are the two to count on.
+ */
+function isSynced(status) {
+    return status.pendingItems === 0;
+}
+export function summariseSync(nodes) {
+    const slaves = nodes.filter((node) => node.role !== 'master');
+    let syncedSlaves = 0;
+    let totalPending = 0;
+    for (const slave of slaves) {
+        const status = slave.syncStatus;
+        // No status means we have not heard from it, which is not the same as
+        // hearing that it is fine. Both counters stay where they are.
+        if (!status)
+            continue;
+        if (isSynced(status))
+            syncedSlaves += 1;
+        totalPending += status.pendingItems;
+    }
+    return { totalSlaves: slaves.length, syncedSlaves, totalPending };
+}
+//# sourceMappingURL=sync-summary.js.map

package/dist/services/sync-summary.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-summary.js","sourceRoot":"","sources":["../../src/services/sync-summary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAkBH;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAS,QAAQ,CAAC,MAAmB;IACnC,OAAO,MAAM,CAAC,YAAY,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAA8B;IAC1D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAE9D,IAAI,YAAY,GAAG,CAAC,CAAC;IACrB,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC;QAChC,sEAAsE;QACtE,8DAA8D;QAC9D,IAAI,CAAC,MAAM;YAAE,SAAS;QAEtB,IAAI,QAAQ,CAAC,MAAM,CAAC;YAAE,YAAY,IAAI,CAAC,CAAC;QACxC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC;IACtC,CAAC;IAED,OAAO,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AACpE,CAAC"}

package/dist/services/sync.rpc-service.d.ts

@@ -8,7 +8,7 @@
  * Slaves call receiveBatch via Netron TCP transport.
  * TCP transport is auth-free (fleet assumes network-level security via WireGuard).
  */
-import type { SyncService, SyncBatch } from './sync.service.js';
+import type { SyncService, SyncBatch, IngestBatchResult } from './sync.service.js';
 export type { SyncBatch };
 import type { ISyncStatus } from '../shared/dto/project.js';
 export declare class SyncRpcService {
@@ -17,18 +17,30 @@ export declare class SyncRpcService {
     /**
      * Receive a sync batch from a slave daemon.
      * Called over Netron TCP transport.
-     * Idempotent — safe to retry on network failure.
+     *
+     * Idempotent — and now actually so. The claim is enforced by a ledger
+     * keyed on the slave's entry id, so a batch replayed after a lost
+     * acknowledgement is recognised rather than ingested twice.
      */
-    receiveBatch(data: SyncBatch): Promise<{
-        accepted: number;
-    }>;
+    receiveBatch(data: SyncBatch): Promise<IngestBatchResult>;
     /**
-     * Drain buffered sync entries — called by master over TCP.
-     * Returns pending entries and marks them as synced atomically.
+     * Hand pending entries to the master — called by the master over TCP.
+     *
+     * Returns them without releasing them. The master calls `ackDrained` once
+     * it holds them; until then a repeat call returns the same entries, which
+     * is what keeps a failure between the two from losing data.
      */
     drainBuffer(data?: {
         limit?: number;
     }): Promise<SyncBatch>;
+    /**
+     * Release entries the master has confirmed it holds.
+     */
+    ackDrained(data: {
+        ids: string[];
+    }): Promise<{
+        released: number;
+    }>;
     /**
      * Get sync status (for webapp monitoring).
      */

package/dist/services/sync.rpc-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.rpc-service.d.ts","sourceRoot":"","sources":["../../src/services/sync.rpc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAChE,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,qBACa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,WAAW;gBAAX,WAAW,EAAE,WAAW;IAErD;;;;OAIG;IAEG,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IAIlE;;;OAGG;IAEG,WAAW,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAIhE;;OAEG;IAEG,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC;CAG5C"}
+{"version":3,"file":"sync.rpc-service.d.ts","sourceRoot":"","sources":["../../src/services/sync.rpc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACnF,YAAY,EAAE,SAAS,EAAE,CAAC;AAC1B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,qBACa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,WAAW;IAAxC,YAA6B,WAAW,EAAE,WAAW,EAAI;IAEzD;;;;;;;OAOG;IAUG,YAAY,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE9D;IAED;;;;;;OAMG;IAEG,WAAW,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC,CAE/D;IAED;;OAEG;IAEG,UAAU,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAEvE;IAED;;OAEG;IAOG,aAAa,IAAI,OAAO,CAAC,WAAW,CAAC,CAE1C;CACF"}

package/dist/services/sync.rpc-service.js

@@ -18,7 +18,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 import { Service, Public } from '@omnitron-dev/titan/decorators';
-import { VIEWER_ROLES } from '../shared/roles.js';
+import { CONTROL_PLANE_READ_ROLES } from '../shared/roles.js';
 let SyncRpcService = class SyncRpcService {
     syncService;
     constructor(syncService) {
@@ -27,21 +27,46 @@ let SyncRpcService = class SyncRpcService {
     /**
      * Receive a sync batch from a slave daemon.
      * Called over Netron TCP transport.
-     * Idempotent — safe to retry on network failure.
+     *
+     * Idempotent — and now actually so. The claim is enforced by a ledger
+     * keyed on the slave's entry id, so a batch replayed after a lost
+     * acknowledgement is recognised rather than ingested twice.
      */
+    // `service_role` cannot be presented today: the daemon issues JWTs whose
+    // role comes from `omnitron_users.role` (admin | operator | viewer), and
+    // titan-auth only mints a service context from `validateApiKey()`, which
+    // needs a `serviceKey` the daemon does not configure. It is left named
+    // because this is one end of an unfinished cross-daemon path — the other
+    // end, `SyncService.setMasterConnection()`, has no production caller
+    // either — and removing it would erase the only statement of the intent.
+    // Reachable in practice by admin and operator.
     async receiveBatch(data) {
         return this.syncService.receiveBatch(data);
     }
     /**
-     * Drain buffered sync entries — called by master over TCP.
-     * Returns pending entries and marks them as synced atomically.
+     * Hand pending entries to the master — called by the master over TCP.
+     *
+     * Returns them without releasing them. The master calls `ackDrained` once
+     * it holds them; until then a repeat call returns the same entries, which
+     * is what keeps a failure between the two from losing data.
      */
     async drainBuffer(data) {
         return this.syncService.drainBuffer(data?.limit);
     }
+    /**
+     * Release entries the master has confirmed it holds.
+     */
+    async ackDrained(data) {
+        return this.syncService.ackDrained(data?.ids ?? []);
+    }
     /**
      * Get sync status (for webapp monitoring).
      */
+    // Read BY the master, not only about it: the master pulls this on every
+    // heartbeat to fill the «Sync» column and the stack's backlog figure. It
+    // reaches the node with `service_role`, which `VIEWER_ROLES` — the human
+    // hierarchy — does not contain, so the node accepted `drainBuffer` from
+    // this very credential and refused the read beside it.
     async getSyncStatus() {
         return this.syncService.getStatus();
     }
@@ -59,7 +84,13 @@ __decorate([
     __metadata("design:returntype", Promise)
 ], SyncRpcService.prototype, "drainBuffer", null);
 __decorate([
-    Public({ auth: { roles: VIEWER_ROLES } }),
+    Public({ auth: { roles: ['admin', 'operator', 'service_role'] } }),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], SyncRpcService.prototype, "ackDrained", null);
+__decorate([
+    Public({ auth: { roles: CONTROL_PLANE_READ_ROLES } }),
     __metadata("design:type", Function),
     __metadata("design:paramtypes", []),
     __metadata("design:returntype", Promise)

package/dist/services/sync.rpc-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync.rpc-service.js","sourceRoot":"","sources":["../../src/services/sync.rpc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;;;;;;;;;;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAM3C,IAAM,cAAc,GAApB,MAAM,cAAc;IACI;IAA7B,YAA6B,WAAwB;QAAxB,gBAAW,GAAX,WAAW,CAAa;IAAG,CAAC;IAEzD;;;;OAIG;IAEG,AAAN,KAAK,CAAC,YAAY,CAAC,IAAe;QAChC,OAAO,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED;;;OAGG;IAEG,AAAN,KAAK,CAAC,WAAW,CAAC,IAAyB;QACzC,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IAEG,AAAN,KAAK,CAAC,aAAa;QACjB,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;IACtC,CAAC;CACF,CAAA;AApBO;IADL,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC;;;;kDAGlE;AAOK;IADL,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC;;;;iDAGlE;AAMK;IADL,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,EAAE,CAAC;;;;mDAGzC;AA5BU,cAAc;IAD1B,OAAO,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;;GACrB,cAAc,CA6B1B"}
+{"version":3,"file":"sync.rpc-service.js","sourceRoot":"","sources":["../../src/services/sync.rpc-service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;;;;;;;;;;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAMvD,IAAM,cAAc,GAApB,MAAM,cAAc;IACI,WAAW;IAAxC,YAA6B,WAAwB;2BAAxB,WAAW;IAAgB,CAAC;IAEzD;;;;;;;OAOG;IACH,yEAAyE;IACzE,yEAAyE;IACzE,yEAAyE;IACzE,uEAAuE;IACvE,yEAAyE;IACzE,qEAAqE;IACrE,yEAAyE;IACzE,+CAA+C;IAEzC,AAAN,KAAK,CAAC,YAAY,CAAC,IAAe;QAChC,OAAO,IAAI,CAAC,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;OAMG;IAEG,AAAN,KAAK,CAAC,WAAW,CAAC,IAAyB;QACzC,OAAO,IAAI,CAAC,WAAW,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAED;;OAEG;IAEG,AAAN,KAAK,CAAC,UAAU,CAAC,IAAuB;QACtC,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,wEAAwE;IACxE,yEAAyE;IACzE,yEAAyE;IACzE,wEAAwE;IACxE,uDAAuD;IAEjD,AAAN,KAAK,CAAC,aAAa;QACjB,OAAO,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;IACtC,CAAC;CACF,CAAA;AApCO;IADL,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC;;;;kDAGlE;AAUK;IADL,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC;;;;iDAGlE;AAMK;IADL,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC;;;;gDAGlE;AAWK;IADL,MAAM,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,wBAAwB,EAAE,EAAE,CAAC;;;;mDAGrD;AAvDU,cAAc;IAD1B,OAAO,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC;;GACrB,cAAc,CAwD1B"}