@cello-protocol/daemon 0.0.3 → 0.0.5

package/dist/transport-composition.js

@@ -0,0 +1,55 @@
+/**
+ * CELLO Daemon — transport-composition.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * Composition-root selection of the transport adapters by CELLO_ENV. Per CLAUDE.md
+ * the daemon composition root instantiates all adapters and fails fast at startup
+ * (not at first session) when a production environment is missing required config.
+ *
+ *   'local' | 'test'                   → in-process stubs (no network).
+ *   'dev' | 'staging' | 'production'   → real adapters; require their backing
+ *                                         dependencies (a TransportDialer for the
+ *                                         selector). Missing config → throw at
+ *                                         startup naming what is missing (AC-010).
+ */
+import { LocalTransportSelectorStub, TransportSelector, } from "./transport-selector.js";
+/** Resolve CELLO_ENV. Unknown/undefined defaults to 'local' (in-process stubs). */
+export function resolveCelloEnv(raw) {
+    switch (raw) {
+        case "local":
+        case "test":
+        case "dev":
+        case "staging":
+        case "production":
+            return raw;
+        default:
+            return "local";
+    }
+}
+/** True for environments that require real (network-backed) transport adapters. */
+export function isProductionVariant(env) {
+    return env === "dev" || env === "staging" || env === "production";
+}
+/**
+ * Build the transport selector for the given environment. Stub for local/test;
+ * real TransportSelector for production variants (requires a TransportDialer).
+ */
+export function createTransportSelector(opts) {
+    const { env, logger, transportDialer, directDialTimeoutMs } = opts;
+    if (!isProductionVariant(env)) {
+        return new LocalTransportSelectorStub();
+    }
+    if (!transportDialer) {
+        throw new Error(`CELLO_ENV='${env}' requires a transport dialer (directory/relay-backed) for the ` +
+            `transport selector, but none was provided to the daemon composition root. The ` +
+            `transport selector cannot dial a counterparty without it — fix the daemon ` +
+            `configuration (config.transportDialer) before startup.`);
+    }
+    return new TransportSelector({ dialer: transportDialer, logger, directDialTimeoutMs });
+}
+// NOTE (CELLO-M7-TRANSPORT-001): there is no createAutoNatService here. The
+// daemon's runtime IAutoNatService is the NodeAutoNatService wrapping the standing
+// receiver node — that node is created inside startDaemon (after this composition
+// runs), so the AutoNAT service is resolved from SessionNodeManager.
+// getStandingReceiverAutoNat() rather than constructed in the composition root.
+// config.autoNatService remains an explicit test override.
+//# sourceMappingURL=transport-composition.js.map

package/dist/transport-composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport-composition.js","sourceRoot":"","sources":["../src/transport-composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,0BAA0B,EAC1B,iBAAiB,GAGlB,MAAM,yBAAyB,CAAC;AAKjC,mFAAmF;AACnF,MAAM,UAAU,eAAe,CAAC,GAAuB;IACrD,QAAQ,GAAG,EAAE,CAAC;QACZ,KAAK,OAAO,CAAC;QACb,KAAK,MAAM,CAAC;QACZ,KAAK,KAAK,CAAC;QACX,KAAK,SAAS,CAAC;QACf,KAAK,YAAY;YACf,OAAO,GAAG,CAAC;QACb;YACE,OAAO,OAAO,CAAC;IACnB,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,mBAAmB,CAAC,GAAa;IAC/C,OAAO,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,YAAY,CAAC;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,IAKvC;IACC,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,mBAAmB,EAAE,GAAG,IAAI,CAAC;IACnE,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,0BAA0B,EAAE,CAAC;IAC1C,CAAC;IACD,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,cAAc,GAAG,iEAAiE;YAChF,gFAAgF;YAChF,4EAA4E;YAC5E,wDAAwD,CAC3D,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,iBAAiB,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,mBAAmB,EAAE,CAAC,CAAC;AACzF,CAAC;AAED,4EAA4E;AAC5E,mFAAmF;AACnF,kFAAkF;AAClF,qEAAqE;AACrE,gFAAgF;AAChF,2DAA2D"}

package/dist/transport-selector.d.ts

@@ -0,0 +1,189 @@
+/**
+ * CELLO Daemon — transport-selector.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * Direct-P2P-by-default transport selection with relay fallback and a best-effort
+ * dcutr hole-punch upgrade.
+ *
+ * ─── Specification (Phase S) ──────────────────────────────────────────────────
+ * Given a FROST-signed SessionAssignment (produced by WIRE-001), choose how to
+ * dial the counterparty's session node:
+ *   1. Read transport_mode from the assignment. This is the ONLY authority for
+ *      the dial strategy (SI-001 / AC-015) — NEVER infer mode from address format.
+ *   2. transport_mode === 'direct' → dial counterparty_session_addrs directly.
+ *   3. direct dial fails OR transport_mode === 'relay' → dial the relay circuit
+ *      address (from the daemon's relay registry, independent of transport_mode —
+ *      AC-006).
+ *   4. After a relay connection is established → attempt a dcutr hole-punch upgrade
+ *      (non-blocking, best-effort). Failure is non-fatal (SI-003).
+ *   5. If BOTH direct and relay fail → terminal 'relay_fallback_also_failed' (AC-008).
+ *
+ * Error code registry (fixed strings — also in CONTEXT.md):
+ *   'autonat_unavailable'                       — internal; no probers reachable.
+ *   'direct_dial_failed_falling_back_to_relay'  — WARN; intermediate, non-fatal.
+ *   'relay_fallback_also_failed'                — terminal session failure.
+ *   'dcutr_upgrade_failed'                      — DEBUG; non-fatal.
+ *
+ * ─── Pseudocode (Phase P) ─────────────────────────────────────────────────────
+ * dial(assignment, { correlationId }):
+ *   mode = assignment.transport_mode            // authoritative
+ *   sessionId = hex(assignment.session_id)
+ *   peerId = assignment.counterparty_session_peer_id
+ *   directAddrs = assignment.counterparty_session_addrs ?? []
+ *   if mode === 'direct':
+ *     try { dialer.dialDirect(peerId, directAddrs); log mode.selected('direct'); return {ok, 'direct'} }
+ *     catch e { log direct_dial.failed(WARN, e.message) }   // fall through
+ *   try { dialer.dialRelay(dialer.relayCircuitAddr(assignment), peerId) }
+ *   catch { return {ok:false, 'relay_fallback_also_failed', guidance} }   // NO mode.selected
+ *   log mode.selected('relay')
+ *   dcutrSettled = (async () => {
+ *     try { dialer.attemptDcutr(peerId); log dcutr.upgraded(INFO); return true }
+ *     catch e { log dcutr.failed(DEBUG, e.message); return false } })()
+ *   return {ok:true, 'relay', dcutrSettled}             // dial does NOT await dcutr
+ */
+import type { SessionAssignment } from "@cello-protocol/protocol-types";
+import type { Logger } from "./types.js";
+import type { Dialability } from "@cello-protocol/transport";
+export declare const TRANSPORT_ERROR: {
+    /** Internal: AutoNAT could not run because no directory-node probers are reachable. */
+    readonly AUTONAT_UNAVAILABLE: "autonat_unavailable";
+    /** WARN-level intermediate, non-fatal: direct dial failed, relay fallback initiated. */
+    readonly DIRECT_DIAL_FAILED_FALLING_BACK: "direct_dial_failed_falling_back_to_relay";
+    /** Terminal: both direct dial and relay fallback failed. */
+    readonly RELAY_FALLBACK_ALSO_FAILED: "relay_fallback_also_failed";
+    /** DEBUG-level non-fatal: dcutr hole-punch upgrade attempt failed. */
+    readonly DCUTR_UPGRADE_FAILED: "dcutr_upgrade_failed";
+};
+/** Default direct-dial timeout (ms). Not a user-facing option (implementation_notes). */
+export declare const DEFAULT_DIRECT_DIAL_TIMEOUT_MS = 5000;
+/**
+ * The outcome of a transport selection. Discriminated by `ok` so the failure
+ * branch is exactly the `{ ok:false, reason, guidance }` shape the MCP layer
+ * surfaces to the caller (AC-008).
+ *
+ * For the relay branch, `dcutrSettled` resolves when the background dcutr attempt
+ * settles — `true` if the connection was hole-punch upgraded to direct, `false`
+ * otherwise. dial() does NOT await it: the session is usable immediately upon the
+ * relay connection (AC-007). Production callers may ignore `dcutrSettled`.
+ */
+export type TransportResult = {
+    ok: true;
+    mode: "direct";
+} | {
+    ok: true;
+    mode: "relay";
+    dcutrSettled: Promise<boolean>;
+} | {
+    ok: false;
+    reason: typeof TRANSPORT_ERROR.RELAY_FALLBACK_ALSO_FAILED;
+    guidance: string;
+};
+export interface TransportDialOptions {
+    /** Correlation ID threaded through every event for this session flow. */
+    correlationId: string;
+}
+/**
+ * Adapter interface for choosing and performing the transport dial.
+ * Real implementation: TransportSelector (drives a TransportDialer + Logger).
+ * Stub: LocalTransportSelectorStub (returns configurable canned results — used by
+ * the composition root when CELLO_ENV is 'local'|'test').
+ */
+export interface ITransportSelector {
+    dial(assignment: SessionAssignment, opts: TransportDialOptions): Promise<TransportResult>;
+}
+/**
+ * The advertised address this daemon offers to the directory for a new session,
+ * derived from the standing receiver's AutoNAT dialability (AC-004 / AC-019):
+ * a direct multiaddr when dialable, the relay circuit address otherwise.
+ */
+export interface SessionNegotiationContext {
+    agentName: string;
+    correlationId: string;
+    advertisedAddress: AdvertisedAddress;
+    params: Record<string, unknown>;
+}
+/**
+ * Outcome of directory session negotiation. On success it carries the
+ * FROST-signed SessionAssignment (transport_mode + counterparty_session_addrs)
+ * that the TransportSelector then consumes.
+ */
+export type SessionNegotiationResult = {
+    ok: true;
+    assignment: SessionAssignment;
+} | {
+    ok: false;
+    reason: string;
+    guidance: string;
+};
+/**
+ * Adapter that performs directory session negotiation and returns the
+ * FROST-signed SessionAssignment. The real implementation is owned by
+ * WIRE-001/SIGNAL-001 (directory signaling); it is injected into the daemon
+ * composition root. When absent, cello_initiate_session reports
+ * directory_signaling_not_configured (it does NOT crash — the transport adapters
+ * are still wired). This is the seam that lets cello_initiate_session drive the
+ * transport selector once an assignment exists (AC-010(c)).
+ */
+export interface SessionNegotiator {
+    negotiate(ctx: SessionNegotiationContext): Promise<SessionNegotiationResult>;
+}
+/**
+ * The low-level dial operations the selector composes. The real implementation
+ * wraps a CelloNode (direct dial + relay circuit dial) plus the daemon's relay
+ * registry. Each operation throws on failure; the selector catches and routes.
+ */
+export interface TransportDialer {
+    /** Dial the counterparty directly. Throws on timeout/refused/unreachable. */
+    dialDirect(peerId: string | undefined, addrs: string[], timeoutMs: number): Promise<void>;
+    /** Dial the counterparty via the relay circuit address. Throws on failure. */
+    dialRelay(relayCircuitAddr: string, peerId: string | undefined): Promise<void>;
+    /**
+     * The relay circuit address for this assignment. Sourced from the daemon's relay
+     * registry (populated during directory connection) — NOT parsed from the
+     * assignment's address fields, and available regardless of transport_mode (AC-006).
+     */
+    relayCircuitAddr(assignment: SessionAssignment): string;
+    /** Attempt a dcutr hole-punch upgrade. Throws on failure (non-fatal — SI-003). */
+    attemptDcutr(peerId: string | undefined): Promise<void>;
+}
+export declare class TransportSelector implements ITransportSelector {
+    #private;
+    constructor(opts: {
+        dialer: TransportDialer;
+        logger: Logger;
+        directDialTimeoutMs?: number;
+    });
+    dial(assignment: SessionAssignment, opts: TransportDialOptions): Promise<TransportResult>;
+}
+/**
+ * In-process transport selector stub. Returns a configurable canned result with
+ * no network access. Selected by the composition root when CELLO_ENV is
+ * 'local' | 'test', so the daemon's session establishment path is wired and does
+ * not crash with "adapter not wired" (AC-010). Defaults to a successful relay
+ * selection (the conservative, always-available transport).
+ */
+export declare class LocalTransportSelectorStub implements ITransportSelector {
+    #private;
+    constructor(result?: TransportResult);
+    dial(_assignment: SessionAssignment, _opts: TransportDialOptions): Promise<TransportResult>;
+    /** Test/composition driver: set the canned result. */
+    setResult(result: TransportResult): void;
+}
+export type AdvertisedAddress = {
+    kind: "direct";
+    addr: string;
+} | {
+    kind: "relay";
+    addr: string;
+};
+/**
+ * Decide what address a node advertises in its SessionAssignment negotiation,
+ * given its AutoNAT dialability and its relay circuit address.
+ *
+ * dialable with a publicAddr → advertise the direct address (transport_mode will
+ * be 'direct'). Otherwise (behind NAT, or AutoNAT unavailable because the
+ * directory is reconnecting) → advertise the relay circuit address (conservative
+ * fallback; transport_mode will be 'relay'). This decision is made once at
+ * session establishment and is immutable for that session (AC-019).
+ */
+export declare function selectAdvertisedAddress(dialability: Dialability, relayCircuitAddr: string): AdvertisedAddress;
+//# sourceMappingURL=transport-selector.d.ts.map

package/dist/transport-selector.d.ts.map

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

package/dist/transport-selector.js

@@ -0,0 +1,195 @@
+/**
+ * CELLO Daemon — transport-selector.ts (CELLO-M7-TRANSPORT-001)
+ *
+ * Direct-P2P-by-default transport selection with relay fallback and a best-effort
+ * dcutr hole-punch upgrade.
+ *
+ * ─── Specification (Phase S) ──────────────────────────────────────────────────
+ * Given a FROST-signed SessionAssignment (produced by WIRE-001), choose how to
+ * dial the counterparty's session node:
+ *   1. Read transport_mode from the assignment. This is the ONLY authority for
+ *      the dial strategy (SI-001 / AC-015) — NEVER infer mode from address format.
+ *   2. transport_mode === 'direct' → dial counterparty_session_addrs directly.
+ *   3. direct dial fails OR transport_mode === 'relay' → dial the relay circuit
+ *      address (from the daemon's relay registry, independent of transport_mode —
+ *      AC-006).
+ *   4. After a relay connection is established → attempt a dcutr hole-punch upgrade
+ *      (non-blocking, best-effort). Failure is non-fatal (SI-003).
+ *   5. If BOTH direct and relay fail → terminal 'relay_fallback_also_failed' (AC-008).
+ *
+ * Error code registry (fixed strings — also in CONTEXT.md):
+ *   'autonat_unavailable'                       — internal; no probers reachable.
+ *   'direct_dial_failed_falling_back_to_relay'  — WARN; intermediate, non-fatal.
+ *   'relay_fallback_also_failed'                — terminal session failure.
+ *   'dcutr_upgrade_failed'                      — DEBUG; non-fatal.
+ *
+ * ─── Pseudocode (Phase P) ─────────────────────────────────────────────────────
+ * dial(assignment, { correlationId }):
+ *   mode = assignment.transport_mode            // authoritative
+ *   sessionId = hex(assignment.session_id)
+ *   peerId = assignment.counterparty_session_peer_id
+ *   directAddrs = assignment.counterparty_session_addrs ?? []
+ *   if mode === 'direct':
+ *     try { dialer.dialDirect(peerId, directAddrs); log mode.selected('direct'); return {ok, 'direct'} }
+ *     catch e { log direct_dial.failed(WARN, e.message) }   // fall through
+ *   try { dialer.dialRelay(dialer.relayCircuitAddr(assignment), peerId) }
+ *   catch { return {ok:false, 'relay_fallback_also_failed', guidance} }   // NO mode.selected
+ *   log mode.selected('relay')
+ *   dcutrSettled = (async () => {
+ *     try { dialer.attemptDcutr(peerId); log dcutr.upgraded(INFO); return true }
+ *     catch e { log dcutr.failed(DEBUG, e.message); return false } })()
+ *   return {ok:true, 'relay', dcutrSettled}             // dial does NOT await dcutr
+ */
+// ─── Error codes (fixed) ──────────────────────────────────────────────────────
+export const TRANSPORT_ERROR = {
+    /** Internal: AutoNAT could not run because no directory-node probers are reachable. */
+    AUTONAT_UNAVAILABLE: "autonat_unavailable",
+    /** WARN-level intermediate, non-fatal: direct dial failed, relay fallback initiated. */
+    DIRECT_DIAL_FAILED_FALLING_BACK: "direct_dial_failed_falling_back_to_relay",
+    /** Terminal: both direct dial and relay fallback failed. */
+    RELAY_FALLBACK_ALSO_FAILED: "relay_fallback_also_failed",
+    /** DEBUG-level non-fatal: dcutr hole-punch upgrade attempt failed. */
+    DCUTR_UPGRADE_FAILED: "dcutr_upgrade_failed",
+};
+const RELAY_FALLBACK_GUIDANCE = "Both direct P2P connection and relay fallback failed. The counterparty may be " +
+    "offline or unreachable from any path. Try again later, or check network connectivity.";
+/** Default direct-dial timeout (ms). Not a user-facing option (implementation_notes). */
+export const DEFAULT_DIRECT_DIAL_TIMEOUT_MS = 5000;
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function sessionIdHex(assignment) {
+    return Buffer.from(assignment.session_id).toString("hex");
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+// ─── TransportSelector (real) ─────────────────────────────────────────────────
+export class TransportSelector {
+    #dialer;
+    #logger;
+    #directDialTimeoutMs;
+    constructor(opts) {
+        this.#dialer = opts.dialer;
+        this.#logger = opts.logger;
+        this.#directDialTimeoutMs = opts.directDialTimeoutMs ?? DEFAULT_DIRECT_DIAL_TIMEOUT_MS;
+    }
+    async dial(assignment, opts) {
+        const sessionId = sessionIdHex(assignment);
+        const { correlationId } = opts;
+        const peerId = assignment.counterparty_session_peer_id;
+        const directAddrs = assignment.counterparty_session_addrs ?? [];
+        // transport_mode is the ONLY authority (SI-001 / AC-015). Never inferred.
+        const mode = assignment.transport_mode;
+        // Step 1: direct dial when transport_mode === 'direct'.
+        if (mode === "direct") {
+            try {
+                await this.#dialer.dialDirect(peerId, directAddrs, this.#directDialTimeoutMs);
+                this.#logger.info("session.transport.mode.selected", {
+                    sessionId,
+                    mode: "direct",
+                    correlationId,
+                });
+                return { ok: true, mode: "direct" };
+            }
+            catch (err) {
+                // Recoverable: log WARN and fall through to relay fallback (AC-006).
+                // failureReason is the actual error message — never ${error}.
+                this.#logger.warn("session.transport.direct_dial.failed", {
+                    sessionId,
+                    counterpartyPeerId: peerId,
+                    failureReason: errMessage(err),
+                    reason: TRANSPORT_ERROR.DIRECT_DIAL_FAILED_FALLING_BACK,
+                    correlationId,
+                });
+            }
+        }
+        // Step 2: relay fallback (transport_mode === 'relay', or direct dial failed).
+        try {
+            const relayAddr = this.#dialer.relayCircuitAddr(assignment);
+            await this.#dialer.dialRelay(relayAddr, peerId);
+        }
+        catch (err) {
+            // Terminal: both direct and relay failed. session.transport.mode.selected is
+            // NOT logged (no mode was selected — AC-008). We DO log the underlying relay
+            // failure reason at WARN so the on-call engineer can diagnose why the
+            // fallback failed (never swallow the exception silently).
+            this.#logger.warn("session.transport.relay_fallback.failed", {
+                sessionId,
+                counterpartyPeerId: peerId,
+                failureReason: errMessage(err),
+                reason: TRANSPORT_ERROR.RELAY_FALLBACK_ALSO_FAILED,
+                correlationId,
+            });
+            return {
+                ok: false,
+                reason: TRANSPORT_ERROR.RELAY_FALLBACK_ALSO_FAILED,
+                guidance: RELAY_FALLBACK_GUIDANCE,
+            };
+        }
+        this.#logger.info("session.transport.mode.selected", {
+            sessionId,
+            mode: "relay",
+            correlationId,
+        });
+        // Step 3: best-effort dcutr upgrade — non-blocking. The session is usable
+        // immediately upon relay connection (AC-007); dcutr runs in the background.
+        const dcutrSettled = this.#attemptDcutr(peerId, sessionId, correlationId);
+        return { ok: true, mode: "relay", dcutrSettled };
+    }
+    async #attemptDcutr(peerId, sessionId, correlationId) {
+        try {
+            await this.#dialer.attemptDcutr(peerId);
+            this.#logger.info("session.transport.dcutr.upgraded", { sessionId, correlationId });
+            return true;
+        }
+        catch (err) {
+            // Non-fatal (SI-003). DEBUG because dcutr failure is expected in many
+            // network topologies. failureReason is error.message — never ${error}.
+            this.#logger.debug("session.transport.dcutr.failed", {
+                sessionId,
+                failureReason: errMessage(err),
+                reason: TRANSPORT_ERROR.DCUTR_UPGRADE_FAILED,
+                correlationId,
+            });
+            return false;
+        }
+    }
+}
+// ─── LocalTransportSelectorStub ───────────────────────────────────────────────
+/**
+ * In-process transport selector stub. Returns a configurable canned result with
+ * no network access. Selected by the composition root when CELLO_ENV is
+ * 'local' | 'test', so the daemon's session establishment path is wired and does
+ * not crash with "adapter not wired" (AC-010). Defaults to a successful relay
+ * selection (the conservative, always-available transport).
+ */
+export class LocalTransportSelectorStub {
+    #result;
+    constructor(result) {
+        this.#result =
+            result ?? { ok: true, mode: "relay", dcutrSettled: Promise.resolve(false) };
+    }
+    async dial(_assignment, _opts) {
+        return this.#result;
+    }
+    /** Test/composition driver: set the canned result. */
+    setResult(result) {
+        this.#result = result;
+    }
+}
+/**
+ * Decide what address a node advertises in its SessionAssignment negotiation,
+ * given its AutoNAT dialability and its relay circuit address.
+ *
+ * dialable with a publicAddr → advertise the direct address (transport_mode will
+ * be 'direct'). Otherwise (behind NAT, or AutoNAT unavailable because the
+ * directory is reconnecting) → advertise the relay circuit address (conservative
+ * fallback; transport_mode will be 'relay'). This decision is made once at
+ * session establishment and is immutable for that session (AC-019).
+ */
+export function selectAdvertisedAddress(dialability, relayCircuitAddr) {
+    if (dialability.dialable && dialability.publicAddr) {
+        return { kind: "direct", addr: dialability.publicAddr };
+    }
+    return { kind: "relay", addr: relayCircuitAddr };
+}
+//# sourceMappingURL=transport-selector.js.map

package/dist/transport-selector.js.map

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