@superbee/core 0.2.0-pre.1 → 0.2.0-pre.11

package/dist/query-filter.js.map

@@ -1 +1 @@
-{"version":3,"file":"query-filter.js","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,GAAgD,EAChD,MAAmB;IAEnB,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACrE,IAAI,MAAM,CAAC,IAAI,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,KAAK,MAAM,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACtE,IAAI,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7E,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IACpE,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,WAAW,GAAG,GAAG,CAAC,WAAsC,CAAC;QAC/D,KAAK,MAAM,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5D,MAAM,GAAG,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;YAC7B,MAAM,MAAM,GACV,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,IAAI;gBAC/B,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACvE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAAE,OAAO,KAAK,CAAC;QAC/C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"query-filter.js","sourceRoot":"","sources":["../src/query-filter.ts"],"names":[],"mappings":"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"}

package/dist/query-order.d.ts

@@ -0,0 +1,22 @@
+export interface MeaningfulChangeOrderKey {
+    id: string;
+    /** The raw selected clock when it is a string, else `""`. */
+    timestamp: string;
+    /** The clock parsed under the bundle's OKF edition, or `null` when missing or invalid. */
+    timestampMs: number | null;
+}
+export declare function meaningfulChangeOrderKey(id: string, frontmatter: {
+    readonly generated?: unknown;
+    readonly timestamp?: unknown;
+}, okfVersion?: string | null): MeaningfulChangeOrderKey;
+/** Newest usable meaningful-change time first; canonical ID in code-unit order for all ties. */
+export declare function compareByMeaningfulChange(a: MeaningfulChangeOrderKey, b: MeaningfulChangeOrderKey): number;
+/** Return a new array of `rows` in newest-first order; the input array is left untouched. */
+export declare function sortByMeaningfulChange<T extends {
+    id: string;
+    frontmatter: {
+        readonly generated?: unknown;
+        readonly timestamp?: unknown;
+    };
+}>(rows: readonly T[], okfVersion?: string | null): T[];
+//# sourceMappingURL=query-order.d.ts.map

package/dist/query-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-order.d.ts","sourceRoot":"","sources":["../src/query-order.ts"],"names":[],"mappings":"AAaA,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,0FAA0F;IAC1F,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,wBAAwB,CACtC,EAAE,EAAE,MAAM,EACV,WAAW,EAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,EAC3E,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,wBAAwB,CAO1B;AAED,gGAAgG;AAChG,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,wBAAwB,EAAE,CAAC,EAAE,wBAAwB,GAAG,MAAM,CAS1G;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CAAC,CAAC,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAAE,EAC1I,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,CAAC,EAAE,CAKL"}

package/dist/query-order.js

@@ -0,0 +1,42 @@
+/**
+ * Newest-first order shared by `list`, `home` and the View Bridge `order: "newest"` query.
+ *
+ * Rows sort by their parsed meaningful-change time (`generated.at`, else legacy `timestamp`),
+ * newest first. Rows with a missing or unparseable time follow every timed row. Every tie,
+ * including the untimed tail, breaks on the canonical ID in UTF-16 code-unit order, which every
+ * host computes identically; `localeCompare` depends on the platform's ICU data.
+ *
+ * Browser-safe and pure.
+ */
+import { parseTimestamp } from "./freshness.js";
+import { meaningfulChangeTimeValue } from "./meaningful-change-time.js";
+export function meaningfulChangeOrderKey(id, frontmatter, okfVersion) {
+    const value = meaningfulChangeTimeValue(frontmatter);
+    return {
+        id,
+        timestamp: typeof value === "string" ? value : "",
+        timestampMs: parseTimestamp(value, okfVersion ?? undefined),
+    };
+}
+/** Newest usable meaningful-change time first; canonical ID in code-unit order for all ties. */
+export function compareByMeaningfulChange(a, b) {
+    if (a.timestampMs !== null && b.timestampMs !== null) {
+        if (a.timestampMs !== b.timestampMs)
+            return b.timestampMs - a.timestampMs;
+    }
+    else if (a.timestampMs !== null) {
+        return -1;
+    }
+    else if (b.timestampMs !== null) {
+        return 1;
+    }
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+/** Return a new array of `rows` in newest-first order; the input array is left untouched. */
+export function sortByMeaningfulChange(rows, okfVersion) {
+    return rows
+        .map((row) => ({ row, key: meaningfulChangeOrderKey(row.id, row.frontmatter, okfVersion) }))
+        .sort((a, b) => compareByMeaningfulChange(a.key, b.key))
+        .map(({ row }) => row);
+}
+//# sourceMappingURL=query-order.js.map

package/dist/query-order.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-order.js","sourceRoot":"","sources":["../src/query-order.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAUxE,MAAM,UAAU,wBAAwB,CACtC,EAAU,EACV,WAA2E,EAC3E,UAA0B;IAE1B,MAAM,KAAK,GAAG,yBAAyB,CAAC,WAAW,CAAC,CAAC;IACrD,OAAO;QACL,EAAE;QACF,SAAS,EAAE,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;QACjD,WAAW,EAAE,cAAc,CAAC,KAAK,EAAE,UAAU,IAAI,SAAS,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,yBAAyB,CAAC,CAA2B,EAAE,CAA2B;IAChG,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QACrD,IAAI,CAAC,CAAC,WAAW,KAAK,CAAC,CAAC,WAAW;YAAE,OAAO,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC;IAC5E,CAAC;SAAM,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;SAAM,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,EAAE,CAAC;QAClC,OAAO,CAAC,CAAC;IACX,CAAC;IACD,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChD,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,sBAAsB,CACpC,IAAkB,EAClB,UAA0B;IAE1B,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,wBAAwB,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC;SAC3F,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC;SACvD,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/dist/remote-backend.d.ts

@@ -2,12 +2,14 @@
  * `RemoteBackend` — a {@link StorageBackend} implemented over the wire-protocol v0
  * reference contract (`docs/WIRE-PROTOCOL.md`, `@superbee/server`).
  *
- * This is the client half of the seam over HTTP: every method maps directly to a wire endpoint,
- * and response versions remain the same content-addressed {@link Version} tokens local backends
- * produce. Tri-backend contract tests pin that invariant.
+ * This is the client half of the seam over HTTP: every method maps directly to a wire endpoint
+ * (a guarded document write may first ask `GET /v0/capabilities` whether the host records
+ * outcomes; see {@link RemoteBackendOptions.maxRetries}), and response versions remain the same
+ * content-addressed {@link Version} tokens local backends produce. Tri-backend contract tests pin
+ * that invariant.
  *
  * Zero new dependencies: it calls an injectable {@link FetchLike} transport
- * (defaulting to the global `fetch`, available on Node >= 20) with a constructed
+ * (defaulting to the global `fetch`, available in every supported Node runtime) with a constructed
  * `Request`. That means the SAME adapter runs against a real HTTP server, or — in
  * tests — directly against an in-process `createRouter(bundle)` function with no
  * sockets: `createRouter` returns exactly the `(req: Request) => Promise<Response>`
@@ -40,6 +42,7 @@
  * This module touches NO filesystem and parses NO markdown — like {@link MemoryBackend},
  * it proves the engine leaks no assumptions beyond the {@link StorageBackend} contract.
  */
+import { type HeadsResult, type RemoteSnapshot } from "./remote-parsers.js";
 import { type Outcome } from "./uncertain-write.js";
 import type { BlobKey, ConceptId, DeleteOptions, HeadResult, OkfDocument, QueryFilter, ReadBlobResult, ReadResult, ReservedFilename, ReservedReadResult, StorageBackend, Version, VersionInfo, WriteOptions } from "./types.js";
 /**
@@ -54,7 +57,7 @@ export interface RemoteBackendOptions {
     baseUrl: string;
     /** Bundle name segment in the `/v0/bundles/{bundle}/…` path. */
     bundle: string;
-    /** Transport override; defaults to the global `fetch` (Node >= 20). Tests inject a router directly. */
+    /** Transport override; defaults to the global `fetch` in supported Node runtimes. Tests inject a router directly. */
     fetchImpl?: FetchLike;
     /**
      * Optional bearer token sent as `Authorization: Bearer <token>` on EVERY request. The
@@ -68,26 +71,28 @@ export interface RemoteBackendOptions {
      * e.g. a Cloudflare D1 cold-start's 500 "storage caused object to be reset" when a hibernated
      * database is first hit) or a network/transport error. Each retry backs off exponentially with
      * jitter. A 4xx (incl. 412 VersionConflict), 401, or any 2xx is a REAL result, never retried.
-     * Default 3; set 0 to disable. Safe because every op is content-addressed + CAS: a retried write
-     * lands the same version or a conflict — possibly SPURIOUS, if a prior attempt actually committed
-     * before its response was lost — but never silent data loss; and a retried read is idempotent.
+     * Default 3; set 0 to disable. A retried read is idempotent.
+     *
+     * A guarded document write (`write` with `expectedVersion`, or `delete` with a content-version
+     * `expectedVersion`) travels with an `Idempotency-Key`: the caller's `requestId`, or else, when
+     * the host's capabilities report `operations`, one minted for that call. Every retry of the
+     * request carries the same key, so while the host keeps the record a retry is answered from the
+     * recorded outcome and cannot apply the write a second time.
+     *
+     * Other guarded writes retry as a plain resubmission: a guarded document write sent without a key
+     * (to a host without `operations`, after a capability question that ended in a transient status,
+     * or resent after the host refused a key minted under a stale answer), a `delete` whose
+     * `expectedVersion` is not a content version, and every guarded reserved-file and blob write,
+     * none of which the wire identifies. Such a retry lands the same version or a conflict, possibly
+     * SPURIOUS if a prior attempt committed before its response was lost. It is not free of lost
+     * updates: versions are content hashes, so if another writer returns the document to the exact
+     * state the premise names before a retry arrives, the retry applies the write again over that
+     * change and reports success. An unconditional write carries no minted key and can simply be
+     * repeated.
      */
     maxRetries?: number;
 }
-/**
- * A non-2xx wire response that is neither a `404` (ENOENT-shaped) nor a `412`
- * ({@link VersionConflict}) — the generic case, carrying the error envelope's `code` alongside
- * the raw HTTP `status`, so a caller can distinguish e.g.
- * `AUTH_REQUIRED` (401, an unauthenticated/misconfigured `--remote`) from `RUNTIME` (5xx, a
- * genuine server-side bug) instead of both collapsing into a generically-classified `Error`.
- */
-export declare class RemoteError extends Error {
-    /** The envelope's `code` field, or a status-derived guess when the envelope is missing/unparseable. */
-    readonly code: string;
-    /** The raw HTTP status that produced this error. */
-    readonly status: number;
-    constructor(message: string, code: string, status: number);
-}
+export { RemoteError } from "./remote-error.js";
 /** The deployment-scoped capability booleans a wire authority reports (`docs/WIRE-PROTOCOL.md`). */
 export interface WireCapabilities {
     history: boolean;
@@ -97,6 +102,15 @@ export interface WireCapabilities {
     blobs: boolean;
     /** Whether document writes carrying `Idempotency-Key` are recorded and readable by lookup. */
     operations: boolean;
+    /** Whether `GET /heads` answers every document id and version under one digest, with `304`. */
+    heads: boolean;
+    /** Whether `GET /snapshot` streams every document as terminated NDJSON. */
+    snapshot: boolean;
+}
+/** Options for {@link RemoteBackend.heads}. */
+export interface HeadsOptions {
+    /** A digest from an earlier `heads` or `snapshot` answer; the authority answers `304` when it still holds it. */
+    ifNoneMatch?: string;
 }
 /**
  * The client half of the wire-protocol v0 contract: implements {@link StorageBackend}
@@ -109,6 +123,8 @@ export declare class RemoteBackend implements StorageBackend {
     private readonly fetchImpl;
     private readonly authToken?;
     private readonly maxRetries;
+    /** The pending or settled answer to whether this host records outcomes; see {@link recordsOutcomes}. */
+    private operationsSupport?;
     constructor(options: RemoteBackendOptions);
     /** The authority's base URL as configured, without a trailing slash. */
     get origin(): string;
@@ -122,12 +138,55 @@ export declare class RemoteBackend implements StorageBackend {
     write(id: ConceptId, doc: OkfDocument, options?: WriteOptions): Promise<Version>;
     /**
      * `GET /v0/capabilities`, deployment-scoped: what this authority implements. `operations` says
-     * whether it records outcomes by request identity. A host without it ignores `Idempotency-Key`
-     * and answers the lookup route with a route-miss `404`, which {@link lookupOperation} cannot
-     * tell from "never recorded"; a consumer that relies on identity checks this once before it
-     * sends any intent. Missing booleans read as `false`.
+     * whether it records outcomes by request identity. The reference router without it refuses any
+     * request carrying `Idempotency-Key`, and the lookup route, with `400 USAGE`; a host that lacks
+     * the lookup route altogether answers it with a route-miss `404`, which {@link lookupOperation}
+     * cannot tell from "never recorded". A consumer that relies on identity checks this once before
+     * it sends any intent. Missing booleans read as `false`.
      */
     wireCapabilities(): Promise<WireCapabilities>;
+    /**
+     * Whether this host records outcomes by request identity, asked through `GET /v0/capabilities`
+     * and shared by concurrent callers. A host that answers anything but a `2xx` with
+     * `operations: true` is treated as not recording them, since a host that does not record them
+     * refuses a key with `400`. That answer is kept for the backend's lifetime, except that a
+     * transient status still returned after `send`'s retries, or a transport failure, is not kept:
+     * the former sends this write unidentified, and the latter rejects the write before it is sent.
+     * A kept yes is also dropped when a minted key meets the host's identity refusal; see
+     * {@link sendDocWrite}.
+     */
+    private recordsOutcomes;
+    private probeOperations;
+    /**
+     * Send a document `PUT` or `DELETE`. When its `Idempotency-Key` was minted here, a kept
+     * `operations` answer may be stale: a host that has since lost its outcome store refuses every
+     * key with the wire's `400` {@link IDENTITY_UNSUPPORTED} before applying anything. That answer
+     * is dropped and the write is sent once more without a key, as to any host without
+     * `operations`. A caller's own `requestId` is never dropped, so its refusal is the answer.
+     */
+    private sendDocWrite;
+    /**
+     * `GET /heads`: every document id and version the authority holds, under one digest, or
+     * `null` when `ifNoneMatch` named the digest it still holds (a `304`: nothing changed). A
+     * `200` is diffed against the caller's own copy: an id missing from `heads` was deleted, a
+     * differing version changed. A `200` without a well-formed digest, whose `count` and rows
+     * disagree, or whose rows digest by the documented recipe to something other than the served
+     * digest, is rejected rather than trusted ({@link parseHeadsAnswer} owns that admission), as
+     * is a `304` to a request that sent no `ifNoneMatch`. Not part of the {@link StorageBackend}
+     * seam.
+     */
+    heads(options?: HeadsOptions): Promise<HeadsResult | null>;
+    /**
+     * `GET /snapshot`: the whole bundle in one response. The header line is parsed before this
+     * resolves, so a non-2xx or a body without a header rejects here with the usual typed error;
+     * the documents then stream through {@link RemoteSnapshot.docs}. Transient retry applies only
+     * to obtaining the response: a body cut mid-stream is reported to the consumer as
+     * `SNAPSHOT_TRUNCATED`, a whole body whose heads do not digest to the header's announcement as
+     * `SNAPSHOT_DIGEST_MISMATCH` ({@link readSnapshotStream} owns the grammar), and re-requesting
+     * is the consumer's decision. Reserved files are not part of a snapshot. Not part of the
+     * {@link StorageBackend} seam.
+     */
+    snapshot(): Promise<RemoteSnapshot>;
     /**
      * `GET /operations/{requestId}`: the authority's recorded outcome for an identified write, or
      * `null` when it holds nothing under that identity (never recorded, or recorded and expired;
@@ -155,7 +214,12 @@ export declare class RemoteBackend implements StorageBackend {
      * `docs/WIRE-PROTOCOL.md`); the engine's `queryHeads` re-filter covers it, per the
      * seam contract (over-returning is fine; semantics live in core).
      */
-    queryHeads(filter?: QueryFilter): Promise<HeadResult[]>;
+    queryHeads(filter?: QueryFilter, options?: {
+        onSkip?: (skip: {
+            id: ConceptId;
+            reason: string;
+        }) => void;
+    }): Promise<HeadResult[]>;
     versions(id: ConceptId): Promise<VersionInfo[]>;
     readReserved(dir: string, name: ReservedFilename): Promise<ReservedReadResult | null>;
     writeReserved(dir: string, name: ReservedFilename, content: string, options?: WriteOptions): Promise<Version>;

package/dist/remote-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-backend.d.ts","sourceRoot":"","sources":["../src/remote-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAKH,OAAO,EAAqB,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEvE,OAAO,KAAK,EACV,OAAO,EACP,SAAS,EACT,aAAa,EAEb,UAAU,EACV,WAAW,EACX,WAAW,EACX,cAAc,EACd,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,OAAO,EACP,WAAW,EACX,YAAY,EACb,MAAM,YAAY,CAAC;AAWpB;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAEhE,sDAAsD;AACtD,MAAM,WAAW,oBAAoB;IACnC,yGAAyG;IACzG,OAAO,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,uGAAuG;IACvG,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM1D;AAED,oGAAoG;AACpG,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,OAAO,CAAC;IACf,8FAA8F;IAC9F,UAAU,EAAE,OAAO,CAAC;CACrB;AAuHD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,oBAAoB;IAQzC,wEAAwE;IACxE,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,wFAAwF;IACxF,OAAO,CAAC,GAAG;YAIG,IAAI;IA0ClB,wEAAwE;YAC1D,OAAO;IAoBf,IAAI,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC;IAYxC,QAAQ,CAAC,GAAG,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAqCjD,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,GAAG,EAAE,WAAW,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB1F;;;;;;OAMG;IACG,gBAAgB,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAenD;;;;;OAKG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;IAY3D,MAAM,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ7C;;;;;OAKG;YACW,QAAQ;IAwBhB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMjD;;;;;;;;;;OAUG;IACG,UAAU,CAAC,MAAM,GAAE,WAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAa3D,QAAQ,CAAC,EAAE,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAiB/C,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAUrF,aAAa,CACjB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAkBnB;;;;;;;;;OASG;IACG,MAAM,CAAC,EAAE,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAwBpE,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAWtD,SAAS,CACb,GAAG,EAAE,OAAO,EACZ,KAAK,EAAE,UAAU,EACjB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,OAAO,CAAC;IAmBnB,8FAA8F;IACxF,UAAU,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,OAAO,CAAC;IAYvE,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAQ1C,SAAS,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;CAiBrD"}
+{"version":3,"file":"remote-backend.d.ts","sourceRoot":"","sources":["../src/remote-backend.ts"],"names":[],"mappings":"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"}