@amalgm/live 0.2.59 → 0.2.61

package/dist/transfer/ranges.d.ts

@@ -1,47 +1,32 @@
 /**
- * Ranged pack reading.
+ * Pack span planning.
  *
- * Sealed envelopes of many small objects live inside one immutable pack.
- * Requests for ranges of the same pack URL made in the same event-loop turn
- * merge into minimal byte spans — one ranged GET per span — and every
- * requester receives exactly its envelope slice. A small hole between wanted
- * ranges is cheaper to read through than to split a request over, so spans
- * merge across gaps up to RANGE_MERGE_GAP_BYTES. Wrong or shifted bytes can
- * never leak: every dispensed slice is still an authenticated envelope the
- * caller opens and hash-verifies.
+ * Sealed envelopes of many small objects live inside one immutable pack. A
+ * download wave knows every member it needs before any byte moves, so the
+ * members of one pack are planned into a few broad byte spans — one ranged
+ * GET per span — instead of a request per member. A small hole between
+ * wanted ranges is cheaper to read through than to split a request over, so
+ * spans merge across gaps up to RANGE_MERGE_GAP_BYTES; a span never grows
+ * past the caller's byte cap, so one planned read always fits the wave's
+ * in-flight memory bound. Wrong or shifted bytes can never leak: every
+ * dispensed slice is still an authenticated envelope the reader opens and
+ * hash-verifies.
  */
-import type { ContentRef } from './refs.js';
 /** Read through holes up to this size rather than splitting a range request. */
 export declare const RANGE_MERGE_GAP_BYTES: number;
-/** Merged span bytes one fetcher may hold in flight at once. Admission of
- * spans — not just of the objects above them — is byte-bounded, so a wide
- * same-turn fan-out can never hold every pack's sealed bytes at once. */
-export declare const SPAN_FETCH_MAX_IN_FLIGHT_BYTES: number;
 export interface ByteSpan {
     readonly offset: number;
     readonly length: number;
 }
-export interface SpanPlan {
+export interface PackSpanPlan {
     /** Minimal disjoint fetch spans, ascending by offset. */
-    readonly spans: ByteSpan[];
-    /** Aligned with the input: which span serves each request, and where the
-     * request's bytes start inside that span. */
-    readonly slices: Array<{
-        readonly span: number;
-        readonly start: number;
-    }>;
+    readonly spans: readonly ByteSpan[];
+    /** Aligned with the input: which span holds each member. */
+    readonly memberSpan: readonly number[];
 }
-/** Merge wanted ranges into minimal fetch spans. Pure planning — no IO. */
-export declare function planSpans(requests: readonly ByteSpan[], mergeGap: number): SpanPlan;
-export interface SpanFetcherPorts {
-    /** Return exactly the requested bytes: the whole object when span is null,
-     * otherwise precisely span.length bytes starting at span.offset. */
-    fetchSpan(url: string, span: ByteSpan | null): Promise<Uint8Array>;
-}
-export interface SpanFetcher {
-    /** The sealed envelope bytes a ref names — a whole standalone object, or
-     * one exact slice of a pack. */
-    fetch(ref: ContentRef): Promise<Uint8Array>;
-}
-export declare function createSpanFetcher(ports: SpanFetcherPorts): SpanFetcher;
+/** Plan one pack's wanted member ranges into broad fetch spans. Pure
+ * planning — no IO. Members merge across holes up to `mergeGap`; a span
+ * stops growing at `maxSpanBytes`, except that a single member larger than
+ * the cap still gets exactly one span of its own. */
+export declare function planPackSpans(members: readonly ByteSpan[], mergeGap: number, maxSpanBytes: number): PackSpanPlan;
 //# sourceMappingURL=ranges.d.ts.map

package/dist/transfer/ranges.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ranges.d.ts","sourceRoot":"","sources":["../../src/transfer/ranges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,QAAY,CAAC;AAE/C;;yEAEyE;AACzE,eAAO,MAAM,8BAA8B,QAAmB,CAAC;AAE/D,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,CAAC;IAC3B;iDAC6C;IAC7C,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAQD,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,QAAQ,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAwBnF;AAED,MAAM,WAAW,gBAAgB;IAC/B;wEACoE;IACpE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,WAAW;IAC1B;oCACgC;IAChC,KAAK,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7C;AAQD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,WAAW,CAyFtE"}
+{"version":3,"file":"ranges.d.ts","sourceRoot":"","sources":["../../src/transfer/ranges.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,QAAY,CAAC;AAE/C,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAQD;;;qDAGqD;AACrD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,SAAS,QAAQ,EAAE,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,GACnB,YAAY,CA6Bd"}

package/dist/transfer/ranges.js

@@ -1,145 +1,59 @@
 /**
- * Ranged pack reading.
+ * Pack span planning.
  *
- * Sealed envelopes of many small objects live inside one immutable pack.
- * Requests for ranges of the same pack URL made in the same event-loop turn
- * merge into minimal byte spans — one ranged GET per span — and every
- * requester receives exactly its envelope slice. A small hole between wanted
- * ranges is cheaper to read through than to split a request over, so spans
- * merge across gaps up to RANGE_MERGE_GAP_BYTES. Wrong or shifted bytes can
- * never leak: every dispensed slice is still an authenticated envelope the
- * caller opens and hash-verifies.
+ * Sealed envelopes of many small objects live inside one immutable pack. A
+ * download wave knows every member it needs before any byte moves, so the
+ * members of one pack are planned into a few broad byte spans — one ranged
+ * GET per span — instead of a request per member. A small hole between
+ * wanted ranges is cheaper to read through than to split a request over, so
+ * spans merge across gaps up to RANGE_MERGE_GAP_BYTES; a span never grows
+ * past the caller's byte cap, so one planned read always fits the wave's
+ * in-flight memory bound. Wrong or shifted bytes can never leak: every
+ * dispensed slice is still an authenticated envelope the reader opens and
+ * hash-verifies.
  */
 /** Read through holes up to this size rather than splitting a range request. */
 export const RANGE_MERGE_GAP_BYTES = 64 * 1024;
-/** Merged span bytes one fetcher may hold in flight at once. Admission of
- * spans — not just of the objects above them — is byte-bounded, so a wide
- * same-turn fan-out can never hold every pack's sealed bytes at once. */
-export const SPAN_FETCH_MAX_IN_FLIGHT_BYTES = 64 * 1024 * 1024;
 function invalidSpan(span) {
     return !Number.isSafeInteger(span.offset) || span.offset < 0
         || !Number.isSafeInteger(span.length) || span.length < 1
         || !Number.isSafeInteger(span.offset + span.length);
 }
-/** Merge wanted ranges into minimal fetch spans. Pure planning — no IO. */
-export function planSpans(requests, mergeGap) {
-    if (requests.length === 0)
-        return { spans: [], slices: [] };
+/** Plan one pack's wanted member ranges into broad fetch spans. Pure
+ * planning — no IO. Members merge across holes up to `mergeGap`; a span
+ * stops growing at `maxSpanBytes`, except that a single member larger than
+ * the cap still gets exactly one span of its own. */
+export function planPackSpans(members, mergeGap, maxSpanBytes) {
+    if (members.length === 0)
+        return { spans: [], memberSpan: [] };
     if (!Number.isSafeInteger(mergeGap) || mergeGap < 0) {
-        throw new Error('range plan received an invalid merge gap');
+        throw new Error('pack span plan received an invalid merge gap');
     }
-    if (requests.some(invalidSpan))
-        throw new Error('range plan received an invalid byte span');
-    const order = requests.map((request, index) => ({ request, index }))
-        .sort((a, b) => a.request.offset - b.request.offset || a.request.length - b.request.length);
+    if (!Number.isSafeInteger(maxSpanBytes) || maxSpanBytes < 1) {
+        throw new Error('pack span plan received an invalid span byte cap');
+    }
+    if (members.some(invalidSpan))
+        throw new Error('pack span plan received an invalid byte span');
+    const order = members.map((member, index) => ({ member, index }))
+        .sort((a, b) => a.member.offset - b.member.offset || a.member.length - b.member.length);
     const spans = [];
-    const slices = new Array(requests.length);
-    for (const { request, index } of order) {
-        const end = request.offset + request.length;
+    const memberSpan = new Array(members.length);
+    for (const { member, index } of order) {
+        const end = member.offset + member.length;
         const current = spans[spans.length - 1];
-        if (current && request.offset <= current.end + mergeGap) {
+        if (current
+            && member.offset <= current.end + mergeGap
+            && (Math.max(current.end, end) - current.offset <= maxSpanBytes || end <= current.end)) {
             current.end = Math.max(current.end, end);
         }
         else {
-            spans.push({ offset: request.offset, end });
+            spans.push({ offset: member.offset, end });
         }
-        slices[index] = { span: spans.length - 1, start: request.offset - spans[spans.length - 1].offset };
+        memberSpan[index] = spans.length - 1;
     }
     return {
         spans: spans.map((span) => ({ offset: span.offset, length: span.end - span.offset })),
-        slices,
-    };
-}
-export function createSpanFetcher(ports) {
-    const pending = new Map();
-    let scheduled = false;
-    // The memory law: merged span bytes in flight are admission-bounded. A
-    // span above the cap admits alone rather than deadlocking.
-    let inFlightSpanBytes = 0;
-    const waitingSpans = [];
-    const spanWeight = (length) => Math.min(length, SPAN_FETCH_MAX_IN_FLIGHT_BYTES);
-    const admitSpan = (length) => new Promise((admit) => {
-        const weight = spanWeight(length);
-        if (inFlightSpanBytes === 0 || inFlightSpanBytes + weight <= SPAN_FETCH_MAX_IN_FLIGHT_BYTES) {
-            inFlightSpanBytes += weight;
-            admit();
-            return;
-        }
-        waitingSpans.push({ weight, admit });
-    });
-    const releaseSpan = (length) => {
-        inFlightSpanBytes -= spanWeight(length);
-        while (waitingSpans.length > 0) {
-            const next = waitingSpans[0];
-            if (inFlightSpanBytes !== 0
-                && inFlightSpanBytes + next.weight > SPAN_FETCH_MAX_IN_FLIGHT_BYTES)
-                return;
-            waitingSpans.shift();
-            inFlightSpanBytes += next.weight;
-            next.admit();
-        }
-    };
-    const flushUrl = async (url, waiters) => {
-        let plan;
-        try {
-            plan = planSpans(waiters.map((waiter) => waiter.range), RANGE_MERGE_GAP_BYTES);
-        }
-        catch (error) {
-            waiters.forEach((waiter) => waiter.reject(error));
-            return;
-        }
-        await Promise.all(plan.spans.map(async (span, spanIndex) => {
-            const served = [];
-            plan.slices.forEach((slice, index) => {
-                if (slice.span === spanIndex)
-                    served.push({ waiter: waiters[index], start: slice.start });
-            });
-            await admitSpan(span.length);
-            try {
-                const bytes = await ports.fetchSpan(url, span);
-                if (bytes.length !== span.length) {
-                    throw new Error(`pack range answered ${bytes.length} bytes where ${span.length} were requested`);
-                }
-                // Copies, not views: a dispensed slice must never pin the whole
-                // merged span buffer for as long as its consumer holds it.
-                served.forEach(({ waiter, start }) => waiter.resolve(bytes.slice(start, start + waiter.range.length)));
-            }
-            catch (error) {
-                served.forEach(({ waiter }) => waiter.reject(error));
-            }
-            finally {
-                releaseSpan(span.length);
-            }
-        }));
-    };
-    const flush = () => {
-        scheduled = false;
-        const batches = [...pending.entries()];
-        pending.clear();
-        for (const [url, waiters] of batches)
-            void flushUrl(url, waiters);
-    };
-    return {
-        fetch(ref) {
-            if (ref.offset == null && ref.length == null) {
-                return ports.fetchSpan(ref.url, null);
-            }
-            const range = { offset: ref.offset ?? -1, length: ref.length ?? -1 };
-            if (invalidSpan(range)) {
-                return Promise.reject(new Error('content ref carries an invalid pack range'));
-            }
-            return new Promise((resolve, reject) => {
-                const waiters = pending.get(ref.url);
-                if (waiters)
-                    waiters.push({ range, resolve, reject });
-                else
-                    pending.set(ref.url, [{ range, resolve, reject }]);
-                if (!scheduled) {
-                    scheduled = true;
-                    setTimeout(flush, 0);
-                }
-            });
-        },
+        memberSpan,
     };
 }
 //# sourceMappingURL=ranges.js.map

package/dist/transfer/ranges.js.map

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

package/dist/transfer/refs.d.ts

@@ -1,13 +1,14 @@
 /**
- * Content-ref brokering for direct content-storage fetches.
+ * Content-ref resolution for direct content-storage fetches.
  *
- * Downloads fetch every storage object straight from content storage. Callers
- * ask where one object lives at a time; the broker coalesces every request
- * made in the same event-loop turn into one batched refs call. The authority
- * answers each object with a short-lived URL and, when the object's sealed
- * envelope rides inside an immutable pack, the exact byte range holding it.
- * URLs are used immediately and never cached — their expiry is the gateway's
- * revocation lever.
+ * Downloads fetch every storage object straight from content storage. A
+ * planned wave resolves the locations of its entire want-list up front — a
+ * handful of batched refs calls, never one per object — so pack members can
+ * be fetched as a few broad spans instead of a request per member. The
+ * authority answers each object with a short-lived URL and, when the
+ * object's sealed envelope rides inside an immutable pack, the exact byte
+ * range holding it. URLs are used immediately and never cached — their
+ * expiry is the gateway's revocation lever.
  */
 /** One law shared with the gateway: the most objects one refs call may name. */
 export declare const CONTENT_REFS_BATCH_OBJECTS = 2048;
@@ -24,12 +25,12 @@ export interface ContentRef {
     readonly offset?: number;
     readonly length?: number;
 }
-export interface RefsBrokerPorts {
-    /** Resolve every named object, returning refs aligned by index. */
+export interface ResolveRefsPorts {
+    /** Resolve one batch of at most CONTENT_REFS_BATCH_OBJECTS named objects,
+     * returning refs aligned by index. */
     requestRefs(objects: readonly ContentObjectName[]): Promise<readonly ContentRef[]>;
 }
-export interface RefsBroker {
-    ref(object: ContentObjectName): Promise<ContentRef>;
-}
-export declare function createRefsBroker(ports: RefsBrokerPorts): RefsBroker;
+/** Resolve every named object's location, batching by the shared wire law.
+ * Answers align with the input. */
+export declare function resolveContentRefs(ports: ResolveRefsPorts, objects: readonly ContentObjectName[]): Promise<readonly ContentRef[]>;
 //# sourceMappingURL=refs.d.ts.map

package/dist/transfer/refs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/transfer/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;qCAEqC;AACrC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,WAAW,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;CACpF;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACrD;AAQD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,UAAU,CA+BnE"}
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../../src/transfer/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAM/C,MAAM,WAAW,iBAAiB;IAChC,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;qCAEqC;AACrC,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B;0CACsC;IACtC,WAAW,CAAC,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAAC;CACpF;AAED;mCACmC;AACnC,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,gBAAgB,EACvB,OAAO,EAAE,SAAS,iBAAiB,EAAE,GACpC,OAAO,CAAC,SAAS,UAAU,EAAE,CAAC,CAkBhC"}

package/dist/transfer/refs.js

@@ -1,45 +1,41 @@
 /**
- * Content-ref brokering for direct content-storage fetches.
+ * Content-ref resolution for direct content-storage fetches.
  *
- * Downloads fetch every storage object straight from content storage. Callers
- * ask where one object lives at a time; the broker coalesces every request
- * made in the same event-loop turn into one batched refs call. The authority
- * answers each object with a short-lived URL and, when the object's sealed
- * envelope rides inside an immutable pack, the exact byte range holding it.
- * URLs are used immediately and never cached — their expiry is the gateway's
- * revocation lever.
+ * Downloads fetch every storage object straight from content storage. A
+ * planned wave resolves the locations of its entire want-list up front — a
+ * handful of batched refs calls, never one per object — so pack members can
+ * be fetched as a few broad spans instead of a request per member. The
+ * authority answers each object with a short-lived URL and, when the
+ * object's sealed envelope rides inside an immutable pack, the exact byte
+ * range holding it. URLs are used immediately and never cached — their
+ * expiry is the gateway's revocation lever.
  */
+import { parallelForEach } from './parallel.js';
 /** One law shared with the gateway: the most objects one refs call may name. */
 export const CONTENT_REFS_BATCH_OBJECTS = 2048;
-export function createRefsBroker(ports) {
-    let pending = [];
-    let scheduled = false;
-    const flush = async () => {
-        scheduled = false;
-        while (pending.length > 0) {
-            const batch = pending.splice(0, CONTENT_REFS_BATCH_OBJECTS);
-            try {
-                const refs = await ports.requestRefs(batch.map((waiter) => waiter.object));
-                if (refs.length !== batch.length) {
-                    throw new Error('content refs answered the wrong number of objects');
-                }
-                batch.forEach((waiter, index) => waiter.resolve(refs[index]));
-            }
-            catch (error) {
-                batch.forEach((waiter) => waiter.reject(error));
-            }
+/** Refs batches a wave resolves concurrently. Batches are control frames —
+ * small either way — so this only bounds simultaneous authority questions. */
+const REFS_RESOLVE_CONCURRENCY = 4;
+/** Resolve every named object's location, batching by the shared wire law.
+ * Answers align with the input. */
+export async function resolveContentRefs(ports, objects) {
+    if (objects.length === 0)
+        return [];
+    const refs = new Array(objects.length);
+    const starts = [];
+    for (let start = 0; start < objects.length; start += CONTENT_REFS_BATCH_OBJECTS) {
+        starts.push(start);
+    }
+    await parallelForEach(starts, REFS_RESOLVE_CONCURRENCY, async (start) => {
+        const batch = objects.slice(start, start + CONTENT_REFS_BATCH_OBJECTS);
+        const answered = await ports.requestRefs(batch);
+        if (answered.length !== batch.length) {
+            throw new Error('content refs answered the wrong number of objects');
         }
-    };
-    return {
-        ref(object) {
-            return new Promise((resolve, reject) => {
-                pending.push({ object, resolve, reject });
-                if (!scheduled) {
-                    scheduled = true;
-                    setTimeout(() => { void flush(); }, 0);
-                }
-            });
-        },
-    };
+        answered.forEach((ref, index) => {
+            refs[start + index] = ref;
+        });
+    });
+    return refs;
 }
 //# sourceMappingURL=refs.js.map

package/dist/transfer/refs.js.map

@@ -1 +1 @@
-{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/transfer/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAgC/C,MAAM,UAAU,gBAAgB,CAAC,KAAsB;IACrD,IAAI,OAAO,GAAa,EAAE,CAAC;IAC3B,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,KAAK,GAAG,KAAK,IAAmB,EAAE;QACtC,SAAS,GAAG,KAAK,CAAC;QAClB,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,0BAA0B,CAAC,CAAC;YAC5D,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC3E,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;oBACjC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;gBACvE,CAAC;gBACD,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAE,CAAC,CAAC,CAAC;YACjE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,GAAG,CAAC,MAAyB;YAC3B,OAAO,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACjD,OAAO,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC1C,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,SAAS,GAAG,IAAI,CAAC;oBACjB,UAAU,CAAC,GAAG,EAAE,GAAG,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;gBACzC,CAAC;YACH,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../../src/transfer/refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,gFAAgF;AAChF,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAE/C;8EAC8E;AAC9E,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAuBnC;mCACmC;AACnC,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,KAAuB,EACvB,OAAqC;IAErC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,IAAI,GAAG,IAAI,KAAK,CAAa,OAAO,CAAC,MAAM,CAAC,CAAC;IACnD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,EAAE,KAAK,IAAI,0BAA0B,EAAE,CAAC;QAChF,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,MAAM,eAAe,CAAC,MAAM,EAAE,wBAAwB,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QACtE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,0BAA0B,CAAC,CAAC;QACvE,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;QAChD,IAAI,QAAQ,CAAC,MAAM,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YAC9B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,GAAG,GAAG,CAAC;QAC5B,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC"}