@optimystic/db-core 0.13.5 → 0.14.0

package/dist/src/cohort-topic/registration/bytes.js

@@ -0,0 +1,32 @@
+/**
+ * Cohort-topic substrate — byte-array helpers shared by the registration store, sharding, and
+ * handoff. Peer ids and topic ids are raw {@link Uint8Array}; these give them stable string map
+ * keys, value equality, and the ascending order the sharding hash relies on.
+ */
+import { compare as compareU8 } from "uint8arrays/compare";
+import { equals as equalsU8 } from "uint8arrays/equals";
+import { bytesToB64url } from "../wire/codec.js";
+/** Stable, collision-free string map key for a byte array (base64url, the package's canonical form). */
+export function bytesKey(b) {
+    return bytesToB64url(b);
+}
+/** Composite key for a registration, `topicKey|participantKey`. */
+export function recordKey(topicId, participantId) {
+    return `${bytesKey(topicId)}|${bytesKey(participantId)}`;
+}
+/** Value equality over byte arrays. */
+export function bytesEqual(a, b) {
+    return equalsU8(a, b);
+}
+/** Lexicographic byte order — the `sort(... by PeerId ascending)` of §Primary and backup sharding. */
+export function compareBytes(a, b) {
+    return compareU8(a, b);
+}
+/** Concatenate two byte arrays into a fresh buffer (the `participantId ‖ cohortEpoch` hash input). */
+export function concatBytes(a, b) {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+}
+//# sourceMappingURL=bytes.js.map

package/dist/src/cohort-topic/registration/bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/bytes.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,MAAM,IAAI,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,wGAAwG;AACxG,MAAM,UAAU,QAAQ,CAAC,CAAa;IACrC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,SAAS,CAAC,OAAmB,EAAE,aAAyB;IACvE,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;AAC1D,CAAC;AAED,uCAAuC;AACvC,MAAM,UAAU,UAAU,CAAC,CAAa,EAAE,CAAa;IACtD,OAAO,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACvB,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,YAAY,CAAC,CAAa,EAAE,CAAa;IACxD,OAAO,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AACxB,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,WAAW,CAAC,CAAa,EAAE,CAAa;IACvD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IAChD,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACd,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IACrB,OAAO,GAAG,CAAC;AACZ,CAAC"}

package/dist/src/cohort-topic/registration/handoff.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Cohort-topic substrate — membership-rotation primary handoff.
+ *
+ * Per `docs/cohort-topic.md` §Membership rotation and primary handoff. When membership changes the
+ * deterministic slot may move a registration's primary. Each member runs this state machine:
+ *
+ * 1. New membership stabilizes; all members compute the new `cohortEpoch`.
+ * 2. Members exchange a "primary inventory" listing the records they hold as primary ({@link start}).
+ * 3. For each record, the new computed primary either already holds it (no-op) or **pulls** it from
+ *    the previous holder ({@link onInventory} → `transport.pull`).
+ * 4. **Resolved (GROUNDING):** the previous primary keeps serving (**dual-serve**) until the new
+ *    primary acknowledges receipt ({@link onAck}) — closing the delivery gap.
+ * 5. Participants discover the new primary on their next ping/delivery (renewal module).
+ *
+ * The gossip *transport* for the inventory comes from a later ticket; it is injected here so the
+ * machine is unit-testable with a mock. The machine is purely cohort-local — FRET is unaware of it.
+ */
+import type { SlotAssigner } from "./sharding.js";
+import type { RegistrationRecord, RegistrationStore } from "./types.js";
+/** Identifies one registration in a {@link PrimaryInventory} or pull/ack exchange. */
+export interface RecordRef {
+    topicId: Uint8Array;
+    participantId: Uint8Array;
+}
+/** A member's list of registrations it currently holds as primary, under the new `cohortEpoch`. */
+export interface PrimaryInventory {
+    /** The advertising member. */
+    from: Uint8Array;
+    /** The new cohort epoch this inventory was computed under. */
+    epoch: Uint8Array;
+    entries: readonly RecordRef[];
+}
+/** Transport the handoff drives; supplied by the cohort-gossip ticket, mocked in tests. */
+export interface HandoffTransport {
+    /** Broadcast this member's primary inventory to the cohort. */
+    sendInventory(inv: PrimaryInventory): void;
+    /** Pull a record this member is now primary for from its previous holder. */
+    pull(from: Uint8Array, ref: RecordRef): Promise<RegistrationRecord | undefined>;
+    /** Acknowledge receipt to the previous holder, ending its dual-serve for `ref`. */
+    ack(to: Uint8Array, ref: RecordRef): void;
+}
+export interface HandoffDeps {
+    store: RegistrationStore;
+    /** This member's own peer id. */
+    self: Uint8Array;
+    slots: SlotAssigner;
+    /** The new (post-rotation) cohort snapshot. */
+    cohort: () => {
+        members: readonly Uint8Array[];
+        cohortEpoch: Uint8Array;
+    };
+    transport: HandoffTransport;
+}
+/** Per-member primary-handoff driver. One instance handles one rotation. */
+export interface MembershipHandoff {
+    /** Step 1+2: recompute under the new epoch, publish this member's inventory, mark hand-offs. */
+    start(): void;
+    /** Step 3: react to a peer's inventory — pull every record now assigned to this member, then ack. */
+    onInventory(inv: PrimaryInventory): Promise<void>;
+    /** Serve a pull from the new primary (this member is the previous holder); stays dual-serving. */
+    onPull(ref: RecordRef): RegistrationRecord | undefined;
+    /** New primary acked receipt: stop dual-serving `ref`. */
+    onAck(ref: RecordRef): void;
+    /** Whether this member should still answer renews for `(topicId, participantId)` right now. */
+    isServing(topicId: Uint8Array, participantId: Uint8Array): boolean;
+}
+/** Build a {@link MembershipHandoff} for one rotation. */
+export declare function createMembershipHandoff(deps: HandoffDeps): MembershipHandoff;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/src/cohort-topic/registration/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/handoff.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAExE,sFAAsF;AACtF,MAAM,WAAW,SAAS;IACzB,OAAO,EAAE,UAAU,CAAC;IACpB,aAAa,EAAE,UAAU,CAAC;CAC1B;AAED,mGAAmG;AACnG,MAAM,WAAW,gBAAgB;IAChC,8BAA8B;IAC9B,IAAI,EAAE,UAAU,CAAC;IACjB,8DAA8D;IAC9D,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;CAC9B;AAED,2FAA2F;AAC3F,MAAM,WAAW,gBAAgB;IAChC,+DAA+D;IAC/D,aAAa,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAC3C,6EAA6E;IAC7E,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,kBAAkB,GAAG,SAAS,CAAC,CAAC;IAChF,mFAAmF;IACnF,GAAG,CAAC,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,iBAAiB,CAAC;IACzB,iCAAiC;IACjC,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,YAAY,CAAC;IACpB,+CAA+C;IAC/C,MAAM,EAAE,MAAM;QAAE,OAAO,EAAE,SAAS,UAAU,EAAE,CAAC;QAAC,WAAW,EAAE,UAAU,CAAA;KAAE,CAAC;IAC1E,SAAS,EAAE,gBAAgB,CAAC;CAC5B;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IACjC,gGAAgG;IAChG,KAAK,IAAI,IAAI,CAAC;IACd,qGAAqG;IACrG,WAAW,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,kGAAkG;IAClG,MAAM,CAAC,GAAG,EAAE,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACvD,0DAA0D;IAC1D,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,+FAA+F;IAC/F,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,GAAG,OAAO,CAAC;CACnE;AAiFD,0DAA0D;AAC1D,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,WAAW,GAAG,iBAAiB,CAE5E"}

package/dist/src/cohort-topic/registration/handoff.js

@@ -0,0 +1,98 @@
+/**
+ * Cohort-topic substrate — membership-rotation primary handoff.
+ *
+ * Per `docs/cohort-topic.md` §Membership rotation and primary handoff. When membership changes the
+ * deterministic slot may move a registration's primary. Each member runs this state machine:
+ *
+ * 1. New membership stabilizes; all members compute the new `cohortEpoch`.
+ * 2. Members exchange a "primary inventory" listing the records they hold as primary ({@link start}).
+ * 3. For each record, the new computed primary either already holds it (no-op) or **pulls** it from
+ *    the previous holder ({@link onInventory} → `transport.pull`).
+ * 4. **Resolved (GROUNDING):** the previous primary keeps serving (**dual-serve**) until the new
+ *    primary acknowledges receipt ({@link onAck}) — closing the delivery gap.
+ * 5. Participants discover the new primary on their next ping/delivery (renewal module).
+ *
+ * The gossip *transport* for the inventory comes from a later ticket; it is injected here so the
+ * machine is unit-testable with a mock. The machine is purely cohort-local — FRET is unaware of it.
+ */
+import { bytesEqual, recordKey } from "./bytes.js";
+class StoreMembershipHandoff {
+    deps;
+    /** Records this member held as primary but no longer is — kept serving until acked. */
+    dualServing = new Set();
+    /** In-flight pulls, so a duplicate inventory does not pull twice. */
+    pulling = new Set();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    start() {
+        const { members, cohortEpoch } = this.deps.cohort();
+        const entries = [];
+        for (const rec of this.deps.store.listAll()) {
+            if (!bytesEqual(rec.primary, this.deps.self)) {
+                continue; // only records this member currently holds as primary
+            }
+            entries.push({ topicId: rec.topicId, participantId: rec.participantId });
+            const { primary } = this.deps.slots.assignSlots(rec.participantId, cohortEpoch, members);
+            if (!bytesEqual(primary, this.deps.self)) {
+                // Primary moved away from this member: keep serving until the new primary acks.
+                this.dualServing.add(recordKey(rec.topicId, rec.participantId));
+            }
+        }
+        this.deps.transport.sendInventory({ from: this.deps.self, epoch: cohortEpoch, entries });
+    }
+    async onInventory(inv) {
+        if (bytesEqual(inv.from, this.deps.self)) {
+            return; // ignore our own inventory
+        }
+        const { members, cohortEpoch } = this.deps.cohort();
+        for (const ref of inv.entries) {
+            await this.maybePull(inv.from, ref, members, cohortEpoch);
+        }
+    }
+    async maybePull(from, ref, members, cohortEpoch) {
+        const { primary, backups } = this.deps.slots.assignSlots(ref.participantId, cohortEpoch, members);
+        if (!bytesEqual(primary, this.deps.self)) {
+            return; // not assigned to this member now
+        }
+        if (this.deps.store.getByParticipant(ref.topicId, ref.participantId) !== undefined) {
+            return; // already hold it (no-op handoff)
+        }
+        const key = recordKey(ref.topicId, ref.participantId);
+        if (this.pulling.has(key)) {
+            return;
+        }
+        this.pulling.add(key);
+        try {
+            const rec = await this.deps.transport.pull(from, ref);
+            if (rec !== undefined) {
+                // Re-stamp the assignment so a later rotation's `start()` recognises this member as primary.
+                this.deps.store.put({ ...rec, primary, backups });
+                this.deps.transport.ack(from, ref); // ends dual-serve at the previous holder
+            }
+        }
+        finally {
+            this.pulling.delete(key);
+        }
+    }
+    onPull(ref) {
+        // Previous holder serves the record; it remains in dualServing until the ack arrives.
+        return this.deps.store.getByParticipant(ref.topicId, ref.participantId);
+    }
+    onAck(ref) {
+        this.dualServing.delete(recordKey(ref.topicId, ref.participantId));
+    }
+    isServing(topicId, participantId) {
+        const { members, cohortEpoch } = this.deps.cohort();
+        const { primary } = this.deps.slots.assignSlots(participantId, cohortEpoch, members);
+        if (bytesEqual(primary, this.deps.self)) {
+            return true;
+        }
+        return this.dualServing.has(recordKey(topicId, participantId));
+    }
+}
+/** Build a {@link MembershipHandoff} for one rotation. */
+export function createMembershipHandoff(deps) {
+    return new StoreMembershipHandoff(deps);
+}
+//# sourceMappingURL=handoff.js.map

package/dist/src/cohort-topic/registration/handoff.js.map

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

package/dist/src/cohort-topic/registration/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./bytes.js";
+export * from "./store.js";
+export * from "./sharding.js";
+export * from "./renewal.js";
+export * from "./handoff.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/cohort-topic/registration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/src/cohort-topic/registration/index.js

@@ -0,0 +1,7 @@
+export * from "./types.js";
+export * from "./bytes.js";
+export * from "./store.js";
+export * from "./sharding.js";
+export * from "./renewal.js";
+export * from "./handoff.js";
+//# sourceMappingURL=index.js.map

package/dist/src/cohort-topic/registration/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/src/cohort-topic/registration/renewal.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Cohort-topic substrate — TTL renewal and failover.
+ *
+ * Per `docs/cohort-topic.md` §TTL and renewal and §Failure modes:
+ *
+ * - Participant pings `primary` every `ttl/3`. Success → primary touches `lastPing` and gossips it.
+ * - Three consecutive ping failures → participant promotes `backups[0]` via a re-attach RPC: a renew
+ *   carrying a **signed `reattach` flag** (no full re-registration). The backup accepts when it holds
+ *   the record locally *and* is a computed backup under the current epoch — re-stamping `primary` to
+ *   itself and serving subsequent plain pings via an epoch-scoped failover override (the unchanged
+ *   `cohortEpoch` still names the dead node as the computed primary). A re-attach answered
+ *   `primary_moved` means a real rotation moved primary to a live member: the participant adopts that
+ *   payload instead of promoting the contacted backup (ignoring a reply that points back at the dead
+ *   primary). **Resolved (GROUNDING):** the participant's `cohortEpoch` hint refreshes lazily — on the
+ *   *next* ping/renewal after failover, not eagerly at failover time.
+ * - All of primary + backups fail → participant re-runs lookup from `d_max` (walk ticket, injected).
+ * - Cohort-side: evict where `now − lastPing > ttl`; eviction is gossiped so members converge.
+ *
+ * Both sides take their transport/gossip by injection so storage + sharding + TTL stay unit-testable
+ * in isolation; db-core never imports FRET or libp2p here.
+ */
+import type { RenewReplyV1, RenewV1 } from "../wire/types.js";
+import type { SlotAssigner } from "./sharding.js";
+import type { RegistrationRecord, RegistrationStore } from "./types.js";
+/** Participant-side TTL renewal: periodic ping with 3-fail backup promotion. */
+export interface RenewalParticipant {
+    /** Run one ping cycle: ping the current primary, count failures, promote/relookup as needed. */
+    pingLoop(): Promise<void>;
+    /** Re-attach to `target` (a backup), carrying the existing record; resolves with the reply. */
+    reattach(target: Uint8Array): Promise<RenewReplyV1>;
+    /**
+     * Best-effort remote tombstone: send a signed withdraw renew to the current primary so the cohort
+     * frees the registration immediately rather than holding it for a full TTL. Swallows any transport
+     * failure (TTL expiry remains the fallback) and does NOT touch the failure counters or trigger
+     * failover — withdraw is one-shot and fire-and-forget.
+     */
+    withdraw(): Promise<void>;
+    /** `ttl/3` cadence the scheduler should call {@link pingLoop} at. */
+    readonly pingIntervalMs: number;
+    /** The participant's current view of its registration (primary/backups). */
+    readonly record: RegistrationRecord;
+    /**
+     * Cached cohort-epoch hint (subscriber-side `cohortHint`). Deliberately *not* refreshed at
+     * failover; a `primary_moved` reply on the next ping refreshes it lazily.
+     */
+    readonly cohortEpochHint: Uint8Array | undefined;
+}
+/** The unsigned body of a renew/re-attach RPC; the injected signer turns it into a {@link RenewV1}. */
+export type UnsignedRenew = Omit<RenewV1, "signature">;
+/** Transport the participant drives; supplied by db-p2p (FRET dial / RouteAndMaybeAct underneath). */
+export interface RenewalParticipantTransport {
+    /** Send a renew/re-attach to `target`; resolves with the reply, rejects on RPC failure. */
+    send(target: Uint8Array, msg: RenewV1): Promise<RenewReplyV1>;
+    /** Primary + all backups unreachable: re-run lookup from `d_max` (walk ticket owns the body). */
+    relookup(): Promise<void>;
+}
+export interface RenewalParticipantDeps {
+    transport: RenewalParticipantTransport;
+    /** Monotonic-ish wall clock in unix ms (injected for deterministic tests). */
+    clock: () => number;
+    /** Signs the renew body; db-p2p supplies the (async) peer-key signature. */
+    sign: (body: UnsignedRenew) => Promise<string>;
+    /** Correlation id matching the original RegisterV1, base64url. */
+    correlationId: string;
+    /** Initial cohort-epoch hint from the registration reply (refreshed lazily thereafter). */
+    initialCohortEpoch?: Uint8Array;
+}
+/** Build a {@link RenewalParticipant} around an initial record. */
+export declare function createRenewalParticipant(initial: RegistrationRecord, deps: RenewalParticipantDeps): RenewalParticipant;
+/** Emits cohort gossip so members converge on the active set after a touch or eviction. */
+export interface RenewalGossip {
+    /** Gossip a `lastPing` touch for `rec`. */
+    touch(rec: RegistrationRecord): void;
+    /** Gossip an eviction for `rec`. */
+    evicted(rec: RegistrationRecord): void;
+}
+export interface RenewalCohortSideDeps {
+    store: RegistrationStore;
+    /** This member's own peer id. */
+    self: Uint8Array;
+    /** Deterministic slot assignment, shared with the handoff. */
+    slots: SlotAssigner;
+    /** Current cohort snapshot — db-p2p supplies it from the membership source. */
+    cohort: () => {
+        members: readonly Uint8Array[];
+        cohortEpoch: Uint8Array;
+    };
+    gossip: RenewalGossip;
+    /**
+     * Optional dual-serve predicate, wired to the rotation handoff's `isServing`. During a handoff
+     * the previous primary is no longer the computed primary but must keep serving until it is acked;
+     * when this returns `true` `onRenew` touches and serves instead of replying `primary_moved`.
+     */
+    isServing?: (topicId: Uint8Array, participantId: Uint8Array) => boolean;
+    /**
+     * Optional participant peer-key signature verifier (db-p2p binds it to the peer-sig primitive over
+     * {@link import("../wire/payloads.js").renewSigningPayload}). It gates the two privileged
+     * participant-attested paths: a `reattach` promotion and a `withdraw` eviction. A renew on either path
+     * whose signature does not verify against the claimed `participantId` must never act — a stray/MITM'd
+     * ping cannot usurp a live primary or evict someone else's registration (§TTL and renewal). Absent →
+     * the gate is skipped (unit tests run without peer crypto); plain pings are never verified here (they
+     * only touch `lastPing`).
+     */
+    verifyParticipantSig?: (renew: RenewV1) => boolean;
+}
+/** Cohort-side TTL handling: touch on renew, redirect on rotation, sweep stale records. */
+export interface RenewalCohortSide {
+    /** Handle an inbound renew. Touches the record, or replies `primary_moved` if this member is no longer primary. */
+    onRenew(msg: RenewV1, now: number): RenewReplyV1;
+    /** Evict every stale record and gossip each eviction; returns the evicted set. */
+    sweepStale(now: number): readonly RegistrationRecord[];
+}
+/** Build a {@link RenewalCohortSide}. */
+export declare function createRenewalCohortSide(deps: RenewalCohortSideDeps): RenewalCohortSide;
+//# sourceMappingURL=renewal.d.ts.map

package/dist/src/cohort-topic/registration/renewal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renewal.d.ts","sourceRoot":"","sources":["../../../../src/cohort-topic/registration/renewal.ts"],"names":[],"mappings":"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"}