@tickernelz/paperclip-pro-adapter-utils 2026.925.0

package/dist/sandbox-callback-bridge-body.js

@@ -0,0 +1,39 @@
+/** JSON can escape each input byte as six characters. Metadata is bounded too. */
+export function sandboxBridgeEnvelopeLimit(maxBodyBytes) {
+    return 6 * maxBodyBytes + 64 * 1024;
+}
+export function encodeSandboxBridgeBody(body, maxBodyBytes) {
+    if (Buffer.byteLength(body) > maxBodyBytes)
+        throw new Error("Bridge body exceeded the configured size limit.");
+    return Buffer.isBuffer(body) ? { body: body.toString("base64"), bodyEncoding: "base64" } : { body };
+}
+/** Self-contained so the same decoder can be embedded in the remote gateway. */
+export function decodeSandboxBridgeBody(envelope, maxBodyBytes) {
+    if (!envelope || typeof envelope.body !== "string")
+        throw new Error("Invalid bridge body.");
+    if (envelope.bodyEncoding === undefined || envelope.bodyEncoding === "utf8") {
+        if (Buffer.byteLength(envelope.body, "utf8") > maxBodyBytes)
+            throw new Error("Bridge body exceeded the configured size limit.");
+        return Buffer.from(envelope.body, "utf8");
+    }
+    if (envelope.bodyEncoding !== "base64")
+        throw new Error("Unsupported bridge body encoding.");
+    const value = envelope.body;
+    if (value.length > 4 * Math.ceil(maxBodyBytes / 3))
+        throw new Error("Bridge body exceeded the configured size limit.");
+    // Buffer.from is permissive; reject malformed input before allocating bytes.
+    if (value.length % 4 !== 0 || /[^A-Za-z0-9+/=]/.test(value) || !/^[A-Za-z0-9+/]*={0,2}$/.test(value)) {
+        throw new Error("Invalid bridge base64 body.");
+    }
+    const bytes = Buffer.from(value, "base64");
+    if (bytes.length > maxBodyBytes)
+        throw new Error("Bridge body exceeded the configured size limit.");
+    if (bytes.toString("base64") !== value)
+        throw new Error("Invalid bridge base64 body.");
+    return bytes;
+}
+export function sandboxBridgeBodyCodecSource() {
+    return [sandboxBridgeEnvelopeLimit, encodeSandboxBridgeBody, decodeSandboxBridgeBody]
+        .map(fn => `const ${fn.name} = ${fn.toString()};`).join("\n");
+}
+//# sourceMappingURL=sandbox-callback-bridge-body.js.map

package/dist/sandbox-callback-bridge-body.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-callback-bridge-body.js","sourceRoot":"","sources":["../src/sandbox-callback-bridge-body.ts"],"names":[],"mappings":"AAMA,kFAAkF;AAClF,MAAM,UAAU,0BAA0B,CAAC,YAAoB;IAC7D,OAAO,CAAC,GAAG,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAqB,EAAE,YAAoB;IACjF,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC/G,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AACtG,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,uBAAuB,CAAC,QAAmC,EAAE,YAAoB;IAC/F,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,CAAC,IAAI,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC5F,IAAI,QAAQ,CAAC,YAAY,KAAK,SAAS,IAAI,QAAQ,CAAC,YAAY,KAAK,MAAM,EAAE,CAAC;QAC5E,IAAI,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,GAAG,YAAY;YAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QAChI,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,QAAQ,CAAC,YAAY,KAAK,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAC7F,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC5B,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACvH,6EAA6E;IAC7E,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrG,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,MAAM,GAAG,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACpG,IAAI,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,OAAO,CAAC,0BAA0B,EAAE,uBAAuB,EAAE,uBAAuB,CAAC;SAClF,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClE,CAAC"}

package/dist/sandbox-callback-bridge-body.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=sandbox-callback-bridge-body.test.d.ts.map

package/dist/sandbox-callback-bridge-body.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-callback-bridge-body.test.d.ts","sourceRoot":"","sources":["../src/sandbox-callback-bridge-body.test.ts"],"names":[],"mappings":""}

package/dist/sandbox-callback-bridge-body.test.js

@@ -0,0 +1,31 @@
+import { runInNewContext } from "node:vm";
+import { describe, expect, it } from "vitest";
+import { decodeSandboxBridgeBody, encodeSandboxBridgeBody, sandboxBridgeBodyCodecSource, sandboxBridgeEnvelopeLimit } from "./sandbox-callback-bridge-body.js";
+const embedded = runInNewContext(`${sandboxBridgeBodyCodecSource()}; ({ encodeSandboxBridgeBody, decodeSandboxBridgeBody })`, { Buffer });
+describe.each([
+    { name: "host", encode: encodeSandboxBridgeBody, decode: decodeSandboxBridgeBody },
+    { name: "generated gateway", encode: embedded.encodeSandboxBridgeBody, decode: embedded.decodeSandboxBridgeBody },
+])("queue body codec: $name", ({ encode, decode }) => {
+    it("preserves old text envelopes and arbitrary binary bytes at the limit", () => {
+        const text = "猫\u0000\n";
+        expect(encode(text, 5)).toEqual({ body: text });
+        expect(decode({ body: text }, 5)).toEqual(Buffer.from(text));
+        expect(decode({ body: text, bodyEncoding: "utf8" }, 5)).toEqual(Buffer.from(text));
+        const bytes = Buffer.from(Array.from({ length: 256 }, (_, index) => index));
+        expect(decode(encode(bytes, bytes.length), bytes.length)).toEqual(bytes);
+        expect(encode(bytes, bytes.length).bodyEncoding).toBe("base64");
+        expect(() => encode(bytes, bytes.length - 1)).toThrow(/size limit/);
+        expect(() => decode(encode(bytes, bytes.length), bytes.length - 1)).toThrow(/size limit/);
+        expect(() => decode({ body: text }, 4)).toThrow(/size limit/);
+    });
+    it.each(["!AAA", "YQ", "YQ=", "YQ===", "YQ==\n", "YR==", "=AAA", "____", "猫"])('rejects malformed or noncanonical base64 "%s"', body => {
+        expect(() => decode({ body, bodyEncoding: "base64" }, 1024)).toThrow(/base64/);
+    });
+    it("rejects unknown encodings and bounds JSON escaping overhead", () => {
+        expect(() => decode({ body: "abc", bodyEncoding: "hex" }, 1024)).toThrow(/encoding/);
+        expect(() => decode({ body: null }, 1024)).toThrow(/Invalid/);
+        const envelope = { id: "request", ...encode("\u0000".repeat(1024), 1024) };
+        expect(Buffer.byteLength(JSON.stringify(envelope))).toBeLessThan(sandboxBridgeEnvelopeLimit(1024));
+    });
+});
+//# sourceMappingURL=sandbox-callback-bridge-body.test.js.map

package/dist/sandbox-callback-bridge-body.test.js.map

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

package/dist/sandbox-callback-bridge.d.ts

@@ -0,0 +1,268 @@
+import type { Duplex } from "node:stream";
+import { type SandboxCallbackBridgeBody } from "./sandbox-callback-bridge-body.js";
+import type { BridgeBodyReservation } from "./http2-bridge-server.js";
+import { type RuntimeSpanRunner, type StartupSpanContext } from "./acpx-engine/startup-timing.js";
+import type { CommandManagedRuntimeRunner } from "./command-managed-runtime.js";
+export declare const SANDBOX_CALLBACK_BRIDGE_ENTRYPOINT = "paperclip-bridge-server.mjs";
+/** The active non-file transport mode. */
+export declare const SANDBOX_CALLBACK_BRIDGE_HTTP2_MODE = "http2_v1";
+export declare const DEFAULT_SANDBOX_CALLBACK_BRIDGE_MAX_BODY_BYTES: number;
+export interface SandboxCallbackBridgeRouteRule {
+    method: string;
+    path: RegExp;
+}
+export declare const DEFAULT_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCallbackBridgeRouteRule[];
+export declare const HTTP2_SANDBOX_CALLBACK_BRIDGE_ROUTE_ALLOWLIST: readonly SandboxCallbackBridgeRouteRule[];
+export declare const DEFAULT_SANDBOX_CALLBACK_BRIDGE_HEADER_ALLOWLIST: readonly ["accept", "content-type", "if-match", "if-none-match", "x-paperclip-github-capability"];
+export interface SandboxCallbackBridgeRequest extends SandboxCallbackBridgeBody {
+    id: string;
+    method: string;
+    path: string;
+    query: string;
+    headers: Record<string, string>;
+    createdAt: string;
+}
+export interface SandboxCallbackBridgeResponse extends SandboxCallbackBridgeBody {
+    id: string;
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+    completedAt: string;
+}
+export interface SandboxCallbackBridgeAsset {
+    localDir: string;
+    entrypoint: string;
+    cleanup(): Promise<void>;
+}
+export interface SandboxCallbackBridgeDirectories {
+    rootDir: string;
+    requestsDir: string;
+    responsesDir: string;
+    logsDir: string;
+    readyFile: string;
+    pidFile: string;
+    logFile: string;
+}
+export interface SandboxCallbackBridgeQueueClient {
+    makeDir(remotePath: string): Promise<void>;
+    makeDirs?(remotePaths: string[]): Promise<void>;
+    listJsonFiles(remotePath: string): Promise<string[]>;
+    fileSize?(remotePath: string): Promise<number>;
+    readTextFile(remotePath: string, maxBytes?: number): Promise<string>;
+    writeTextFile(remotePath: string, body: string): Promise<void>;
+    writeResponseFile?(responsePath: string, body: string, options?: {
+        requestPath?: string | null;
+    }): Promise<{
+        wrote: boolean;
+    }>;
+    rename(fromPath: string, toPath: string): Promise<void>;
+    remove(remotePath: string): Promise<void>;
+}
+export interface SandboxCallbackBridgeWorkerHandle {
+    stop(options?: {
+        drainTimeoutMs?: number;
+    }): Promise<void>;
+}
+export interface StartedSandboxCallbackBridgeServer {
+    baseUrl: string;
+    host: string;
+    port: number;
+    pid: number;
+    directories: SandboxCallbackBridgeDirectories;
+    stop(): Promise<void>;
+}
+export declare function createSandboxCallbackBridgeToken(bytes?: number): string;
+export declare function authorizeSandboxCallbackBridgeRequestWithRoutes(request: Pick<SandboxCallbackBridgeRequest, "method" | "path">, routes?: readonly SandboxCallbackBridgeRouteRule[]): string | null;
+export declare function sanitizeSandboxCallbackBridgeHeaders(headers: Record<string, string>, allowlist?: readonly string[]): Record<string, string>;
+export declare function sandboxCallbackBridgeDirectories(rootDir: string): SandboxCallbackBridgeDirectories;
+export declare function buildSandboxCallbackBridgeEnv(input: {
+    queueDir: string;
+    bridgeToken: string;
+    host?: string;
+    port?: number | null;
+    pollIntervalMs?: number | null;
+    responseTimeoutMs?: number | null;
+    maxQueueDepth?: number | null;
+    maxBodyBytes?: number | null;
+}): Record<string, string>;
+export declare function createSandboxCallbackBridgeAsset(): Promise<SandboxCallbackBridgeAsset>;
+export declare function createFileSystemSandboxCallbackBridgeQueueClient(): SandboxCallbackBridgeQueueClient;
+export declare function createCommandManagedSandboxCallbackBridgeQueueClient(input: {
+    runner: CommandManagedRuntimeRunner;
+    remoteCwd: string;
+    timeoutMs?: number | null;
+    shellCommand?: "bash" | "sh" | null;
+}): SandboxCallbackBridgeQueueClient;
+export declare function startSandboxCallbackBridgeWorker(input: {
+    client: SandboxCallbackBridgeQueueClient;
+    queueDir: string;
+    pollIntervalMs?: number | null;
+    iterationTimeoutMs?: number | null;
+    watchdogTimeoutMs?: number | null;
+    abortedHandlerGraceMs?: number | null;
+    authorizeRequest?: (request: SandboxCallbackBridgeRequest) => string | null | Promise<string | null>;
+    handleRequest: (request: Omit<SandboxCallbackBridgeRequest, "body" | "bodyEncoding"> & {
+        body: string | Buffer;
+    }, options?: {
+        signal: AbortSignal;
+        reservation: BridgeBodyReservation;
+    }) => Promise<{
+        status: number;
+        headers?: Record<string, string>;
+        body?: string | Buffer;
+    }>;
+    maxBodyBytes?: number | null;
+    getRuntimeParentContext?: () => StartupSpanContext | undefined;
+    runtimeSpan?: RuntimeSpanRunner;
+}): Promise<SandboxCallbackBridgeWorkerHandle>;
+/**
+ * Content-hash-skip write of a Paperclip-authored text file into the sandbox, in
+ * a SINGLE remote exec. The body's sha256 is computed on the host; the one shell
+ * round-trip skips the write entirely when the remote file already hashes to the
+ * same value (warm start — 0 write execs), otherwise it uploads (base64 over
+ * stdin), verifies the decoded bytes, and atomically renames into place. A
+ * PID-liveness lock serializes concurrent writers to the same path and the
+ * verify step guards against a torn upload.
+ *
+ * Fail loudly: a non-zero remote exit (surfaced by `requireSuccessfulResult`) or
+ * malformed result JSON throws rather than silently re-uploading and masking a
+ * failed check. The only intentional degradation is when the remote has neither
+ * `sha256sum` nor `shasum` — then the skip cannot be proven and we conservatively
+ * re-upload (and the post-upload verify is best-effort, as noted inline).
+ */
+export declare function syncRemoteTextFileWithHashSkip(input: {
+    runner: CommandManagedRuntimeRunner;
+    remoteCwd: string;
+    remoteDir: string;
+    remotePath: string;
+    body: string;
+    label: string;
+    action: string;
+    lockDir: string;
+    timeoutMs?: number | null;
+    shellCommand?: "bash" | "sh" | null;
+}): Promise<{
+    uploaded: boolean;
+    sha256: string;
+}>;
+export declare function syncSandboxCallbackBridgeEntrypoint(input: {
+    runner: CommandManagedRuntimeRunner;
+    remoteCwd: string;
+    assetRemoteDir: string;
+    bridgeAsset: SandboxCallbackBridgeAsset;
+    timeoutMs?: number | null;
+    shellCommand?: "bash" | "sh" | null;
+}): Promise<{
+    remoteEntrypoint: string;
+    sha256: string;
+    uploaded: boolean;
+}>;
+export declare function startSandboxCallbackBridgeServer(input: {
+    runner: CommandManagedRuntimeRunner;
+    remoteCwd: string;
+    assetRemoteDir: string;
+    queueDir: string;
+    bridgeToken: string;
+    bridgeAsset?: SandboxCallbackBridgeAsset | null;
+    host?: string;
+    port?: number | null;
+    pollIntervalMs?: number | null;
+    responseTimeoutMs?: number | null;
+    timeoutMs?: number | null;
+    nodeCommand?: string;
+    shellCommand?: "bash" | "sh" | null;
+    maxQueueDepth?: number | null;
+    maxBodyBytes?: number | null;
+}): Promise<StartedSandboxCallbackBridgeServer>;
+/**
+ * Constant-time bridge-token compare. Both this sandbox gateway and the host
+ * server in `http2-bridge-server.ts` import this one helper, so the gateway
+ * check and the independent host check (accepted security fix 4) apply the
+ * exact same comparison rule. A length mismatch returns `false` without a
+ * `timingSafeEqual` call, because `timingSafeEqual` throws on unequal buffer
+ * lengths; both operands are bridge tokens of near-fixed length, so this one
+ * length branch leaks no useful timing signal.
+ */
+export declare function compareBridgeTokensConstantTime(expected: string, received: string | null | undefined): boolean;
+/** One local request the gateway forwards as one HTTP/2 stream. */
+export interface SandboxHttp2BridgeGatewayRequest {
+    method: string;
+    path: string;
+    query: string;
+    headers: Record<string, string>;
+    body: Buffer;
+    /**
+     * The token the local caller presented. The gateway check (accepted
+     * security fix 4 keeps this alongside the independent host check) compares
+     * it against the per-run bridge token before it opens a stream.
+     */
+    receivedToken: string | null | undefined;
+}
+/** The response one forwarded HTTP/2 stream carried back. */
+export interface SandboxHttp2BridgeGatewayResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: Buffer;
+}
+export interface SandboxHttp2BridgeGateway {
+    /** Forward one local request as one HTTP/2 stream over the client session. */
+    forwardRequest(request: SandboxHttp2BridgeGatewayRequest): Promise<SandboxHttp2BridgeGatewayResponse>;
+    /** Close the HTTP/2 client session. Safe to call more than one time. */
+    close(): Promise<void>;
+}
+export interface CreateSandboxHttp2BridgeGatewayOptions {
+    /**
+     * The per-run bridge token. The gateway checks every request against it,
+     * then attaches it to the outbound HTTP/2 stream as the `authorization`
+     * header, so the host can run its own independent check.
+     */
+    bridgeToken: string;
+    /**
+     * Open the transport the HTTP/2 client session runs on. Returns a `Duplex`
+     * already connected to the host — the sandbox process's own channel in
+     * production, or one side of a paired in-memory `Duplex` in a test.
+     */
+    createConnection: () => Duplex;
+    /** The `:authority` pseudo-header value. The channel carries no real network
+     * address, so this is a fixed label. The default is `bridge.internal`. */
+    authority?: string;
+    /** The header allowlist applied to every outbound request. The default is
+     * {@link DEFAULT_SANDBOX_CALLBACK_BRIDGE_HEADER_ALLOWLIST}. */
+    headerAllowlist?: readonly string[];
+    /**
+     * The sink for a GOAWAY the host sends. The host names the last client
+     * stream ID it processed; a caller classifies each of its own dispatched
+     * stream IDs against it with `classifyStreamAgainstGoaway` in
+     * `http2-bridge-server.ts` to know which requests need a retry elsewhere.
+     */
+    onGoaway?: (record: {
+        lastStreamId: number;
+        errorCode: number;
+    }) => void;
+}
+/**
+ * Create the sandbox HTTP/2 client gateway. It opens one HTTP/2 client
+ * session on the transport `createConnection` returns, and forwards each
+ * local request the caller hands it (already checked against the bridge
+ * token — see {@link SandboxHttp2BridgeGatewayRequest.receivedToken}) as one
+ * HTTP/2 stream. It keeps the header allowlist on the sandbox side, exactly
+ * as the file-mode gateway does.
+ */
+export declare function createSandboxHttp2BridgeGateway(options: CreateSandboxHttp2BridgeGatewayOptions): SandboxHttp2BridgeGateway;
+/**
+ * Return the exact zero-dependency codec source the generated duplex gateway
+ * embeds. A test wraps this source and calls `encodeDuplexFrame` to prove the
+ * embedded copy encodes the READY frame the same way the host encode side does.
+ * The source declares `encodeDuplexFrame` and `DUPLEX_FRAME_VERSION`, but exports
+ * neither; a caller wraps it to read those names.
+ */
+export declare function getSandboxDuplexGatewayCodecSource(): string;
+/**
+ * Return the exact zero-dependency ledger source the generated gateway
+ * embeds. A test wraps this source and calls `createBridgeProcessBodyLedger`
+ * to prove the embedded copy reserves and releases bytes correctly, with no
+ * spawned process involved.
+ */
+export declare function getSandboxBridgeProcessBodyLedgerSource(): string;
+export declare function getSandboxCallbackBridgeServerSource(): string;
+//# sourceMappingURL=sandbox-callback-bridge.d.ts.map

package/dist/sandbox-callback-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-callback-bridge.d.ts","sourceRoot":"","sources":["../src/sandbox-callback-bridge.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAKL,KAAK,yBAAyB,EAC/B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACxB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAiEhF,eAAO,MAAM,kCAAkC,gCAAgC,CAAC;AAYhF,0CAA0C;AAC1C,eAAO,MAAM,kCAAkC,aAAa,CAAC;AAY7D,eAAO,MAAM,8CAA8C,QAAgC,CAAC;AAE5F,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAOD,eAAO,MAAM,+CAA+C,EAAE,SAAS,8BAA8B,EAmG3F,CAAC;AAGX,eAAO,MAAM,6CAA6C,2CAAkD,CAAC;AAE7G,eAAO,MAAM,gDAAgD,YAC3D,QAAQ,EACR,cAAc,EACd,UAAU,EACV,eAAe,EACf,+BAA+B,CACvB,CAAC;AAEX,MAAM,WAAW,4BAA6B,SAAQ,yBAAyB;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,6BAA8B,SAAQ,yBAAyB;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,gCAAgC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gCAAgC;IAC/C,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAK3C,QAAQ,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACrD,QAAQ,CAAC,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/C,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrE,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,iBAAiB,CAAC,CAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC7B,GACA,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iCAAiC;IAChD,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,MAAM,WAAW,kCAAkC;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,gCAAgC,CAAC;IAC9C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAgID,wBAAgB,gCAAgC,CAAC,KAAK,SAA6B,GAAG,MAAM,CAE3F;AAED,wBAAgB,+CAA+C,CAC7D,OAAO,EAAE,IAAI,CAAC,4BAA4B,EAAE,QAAQ,GAAG,MAAM,CAAC,EAC9D,MAAM,GAAE,SAAS,8BAA8B,EAAoD,GAClG,MAAM,GAAG,IAAI,CAKf;AAED,wBAAgB,oCAAoC,CAClD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,SAAS,GAAE,SAAS,MAAM,EAAqD,GAC9E,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB;AAED,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,MAAM,GAAG,gCAAgC,CAUlG;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBzB;AAED,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,0BAA0B,CAAC,CAW5F;AAED,wBAAgB,gDAAgD,IAAI,gCAAgC,CA+HnG;AAED,wBAAgB,oDAAoD,CAAC,KAAK,EAAE;IAC1E,MAAM,EAAE,2BAA2B,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACrC,GAAG,gCAAgC,CAuInC;AAmBD,wBAAsB,gCAAgC,CAAC,KAAK,EAAE;IAC5D,MAAM,EAAE,gCAAgC,CAAC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAI/B,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAInC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAIlC,qBAAqB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,4BAA4B,KAAK,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAQrG,aAAa,EAAE,CACb,OAAO,EAAE,IAAI,CAAC,4BAA4B,EAAE,MAAM,GAAG,cAAc,CAAC,GAAG;QAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,EAChG,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,qBAAqB,CAAA;KAAE,KAClE,OAAO,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACxB,CAAC,CAAC;IACH,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAM7B,uBAAuB,CAAC,EAAE,MAAM,kBAAkB,GAAG,SAAS,CAAC;IAM/D,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC,GAAG,OAAO,CAAC,iCAAiC,CAAC,CAwxB7C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,8BAA8B,CAAC,KAAK,EAAE;IAC1D,MAAM,EAAE,2BAA2B,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IAGb,KAAK,EAAE,MAAM,CAAC;IAGd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACrC,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA6EjD;AAED,wBAAsB,mCAAmC,CAAC,KAAK,EAAE;IAC/D,MAAM,EAAE,2BAA2B,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,0BAA0B,CAAC;IACxC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;CACrC,GAAG,OAAO,CAAC;IAAE,gBAAgB,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAAE,CAAC,CAqB3E;AAED,wBAAsB,gCAAgC,CAAC,KAAK,EAAE;IAC5D,MAAM,EAAE,2BAA2B,CAAC;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAChD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B,GAAG,OAAO,CAAC,kCAAkC,CAAC,CAkI9C;AAWD;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC,OAAO,CAKT;AAID,mEAAmE;AACnE,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC1C;AAED,6DAA6D;AAC7D,MAAM,WAAW,iCAAiC;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,yBAAyB;IACxC,8EAA8E;IAC9E,cAAc,CACZ,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,iCAAiC,CAAC,CAAC;IAC9C,wEAAwE;IACxE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,sCAAsC;IACrD;;;;OAIG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,MAAM,CAAC;IAC/B;8EAC0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;mEAC+D;IAC/D,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;CAC1E;AA8DD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,sCAAsC,GAC9C,yBAAyB,CAyC3B;AAsBD;;;;;;GAMG;AACH,wBAAgB,kCAAkC,IAAI,MAAM,CAE3D;AAkCD;;;;;GAKG;AACH,wBAAgB,uCAAuC,IAAI,MAAM,CAEhE;AAED,wBAAgB,oCAAoC,IAAI,MAAM,CA0oB7D"}