@open-everywhere/provider-notion 0.1.0

package/dist/agent/memory/blocks.js

@@ -0,0 +1,264 @@
+// Notion blocks → Markdown codec (PURE — no network), the read half of the Notion
+// memory backing (docs/capabilities/memory.md "Notion backing"). Notion stores typed blocks,
+// not raw markdown, so a domain's read-only memory page is rendered to markdown the
+// agent reads. Kept separate from the API client so it's trivially unit-testable.
+//
+// v1 renders the common block types (headings, paragraphs, lists, to-dos, quotes,
+// callouts, code, dividers, equations) with bold/italic/code inline annotations; nested
+// content blocks (a toggle's or list item's children) recurse with indentation. child_page
+// / child_database blocks are NOT rendered inline — they're pulled as separate pages by
+// the walker (memory.ts). Unknown TEXT block types degrade to their plain text.
+//
+// Rich blocks that can't be faithfully rendered to markdown (image, table, embed, …) are
+// NOT silently dropped — they become a typed PLACEHOLDER carrying the block `type` + `id`
+// (+ a caption/url hint when cheap), telling the agent to fetch that block by id via the
+// Notion tools. So the 95% text stays clean and the rare rich block escalates to the tool
+// by id — no silent data loss. (docs/capabilities/memory.md "rich-block placeholders".)
+//
+// The WRITE half is {@link blocksFromMarkdown} (OPE-70) — markdown lines → the block payloads
+// Notion's own block-append API takes. It is deliberately NOT a general markdown parser: it maps
+// the shapes `renderBlocks` above emits, and it PROVES each batch by rendering the blocks it built
+// back through `renderBlocks`, refusing any difference. So the codec's two halves cannot drift.
+//
+// 🔴 THE PROOF IS AGAINST THIS CODEC, NOT AGAINST NOTION. It compares what we SEND with what
+// `renderBlocks` makes of it; it never sees what the vendor stores or returns. If Notion normalises
+// a payload we send, the divergence shows up on the next pull as an append-only refusal — loud, but
+// after the fact. No offline tier can close that gap; only a live append can.
+/** Block types that are SUB-PAGES, not inline content. */
+export const PAGE_BLOCK_TYPES = new Set(["child_page", "child_database"]);
+/**
+ * Rich / non-text block types that markdown can't faithfully carry → rendered as a typed
+ * placeholder (type + id + hint) instead of being dropped. `table` is here too: its rows
+ * (`table_row` children) aren't rendered, so we point the agent at the source. The agent
+ * fetches the real block BY ID via the Notion tools when it needs it.
+ */
+const PLACEHOLDER_BLOCK_TYPES = new Set([
+    "image", "video", "audio", "file", "pdf", "embed", "bookmark", "link_preview", "table", "unsupported",
+]);
+/** A cheap one-line hint for a placeholder: a caption or a url, when present. */
+function placeholderHint(block) {
+    const pl = block[block.type];
+    if (!pl)
+        return "";
+    const cap = pl.caption && pl.caption.length > 0 ? renderRich(pl.caption) : "";
+    if (cap)
+        return ` "${cap}"`;
+    if (typeof pl.url === "string" && pl.url.length > 0)
+        return ` (${pl.url})`;
+    return "";
+}
+/** The placeholder line for an un-renderable rich block — carries type + id + how to fetch. */
+function placeholderLine(block, indent) {
+    const id = typeof block.id === "string" && block.id.length > 0 ? ` id=${block.id}` : "";
+    return `${indent}> ⛏ [notion:${block.type}${id}]${placeholderHint(block)} — rich block not rendered; fetch by id via the Notion tools.`;
+}
+function renderRich(rich, resolve) {
+    if (!rich)
+        return "";
+    return rich
+        .map((rt) => {
+        // A page mention/link → rewrite to the on-disk file (when it's in this subtree).
+        if (resolve && rt.type === "mention" && rt.mention?.page?.id) {
+            const target = resolve(rt.mention.page.id);
+            if (target)
+                return `[${rt.plain_text || target.title}](${target.path})`;
+        }
+        let t = rt.plain_text ?? rt.text?.content ?? "";
+        const a = rt.annotations ?? {};
+        if (a.code)
+            t = `\`${t}\``;
+        if (a.bold)
+            t = `**${t}**`;
+        if (a.italic)
+            t = `*${t}*`;
+        return t;
+    })
+        .join("");
+}
+function payload(block) {
+    return block[block.type] ?? {};
+}
+/** Render one block (with its nested children) to markdown lines. */
+function renderBlock(block, depth, resolve) {
+    const indent = "  ".repeat(depth);
+    // Rich/non-text block we can't faithfully render → typed placeholder, and DON'T recurse
+    // its children (e.g. a table's rows would render as junk). The agent fetches it by id.
+    if (PLACEHOLDER_BLOCK_TYPES.has(block.type))
+        return [placeholderLine(block, indent)];
+    const p = payload(block);
+    const rich = renderRich(p.rich_text, resolve);
+    const lines = [];
+    switch (block.type) {
+        case "link_to_page": {
+            // A standalone link to another page → an on-disk link when it's in this subtree.
+            const pid = block.link_to_page?.page_id;
+            const target = pid && resolve ? resolve(pid) : undefined;
+            if (target)
+                lines.push(`${indent}[${target.title}](${target.path})`);
+            else if (pid)
+                lines.push(`${indent}(link to a page outside this memory)`);
+            break;
+        }
+        case "heading_1":
+            lines.push(`# ${rich}`);
+            break;
+        case "heading_2":
+            lines.push(`## ${rich}`);
+            break;
+        case "heading_3":
+            lines.push(`### ${rich}`);
+            break;
+        case "bulleted_list_item":
+            lines.push(`${indent}- ${rich}`);
+            break;
+        case "numbered_list_item":
+            lines.push(`${indent}1. ${rich}`);
+            break;
+        case "to_do":
+            lines.push(`${indent}- [${p.checked ? "x" : " "}] ${rich}`);
+            break;
+        case "toggle":
+            lines.push(`${indent}- ${rich}`);
+            break;
+        case "quote":
+        case "callout":
+            lines.push(`> ${rich}`);
+            break;
+        case "code":
+            lines.push("```" + (p.language ?? ""), rich, "```");
+            break;
+        case "equation": {
+            // Notion equation blocks carry `expression` (KaTeX), not rich_text — render losslessly.
+            const expr = block.equation?.expression ?? rich;
+            lines.push(`${indent}$$ ${expr} $$`);
+            break;
+        }
+        case "divider":
+            lines.push("---");
+            break;
+        default:
+            if (rich)
+                lines.push(`${indent}${rich}`);
+            break;
+    }
+    // Recurse into nested content children (list nesting, toggles). Page children are
+    // excluded here — the walker pulls them as separate files.
+    if (block.children) {
+        const nestDepth = block.type === "bulleted_list_item" || block.type === "numbered_list_item" || block.type === "to_do" || block.type === "toggle" ? depth + 1 : depth;
+        for (const child of block.children) {
+            if (PAGE_BLOCK_TYPES.has(child.type))
+                continue;
+            lines.push(...renderBlock(child, nestDepth, resolve));
+        }
+    }
+    return lines;
+}
+/**
+ * Render a page's top-level content blocks to a markdown document. `resolve` (optional)
+ * rewrites page mentions / link_to_page blocks to on-disk relative links.
+ */
+export function renderBlocks(blocks, resolve) {
+    const out = [];
+    for (const b of blocks) {
+        if (PAGE_BLOCK_TYPES.has(b.type))
+            continue;
+        out.push(...renderBlock(b, 0, resolve));
+    }
+    return out.join("\n").replace(/\n{3,}/g, "\n\n").trim() + "\n";
+}
+/**
+ * The markdown lines one page's rendered content carries, with blank lines dropped and trailing
+ * whitespace trimmed. THE COMPARISON UNIT for the write path (memory.ts).
+ *
+ * Blank lines are dropped because Notion has no blank-line block: a blank line cannot survive a
+ * round trip through `renderBlocks`, so counting one as a difference would make every write look
+ * like an un-expressible edit.
+ */
+export function contentLines(markdown) {
+    return markdown
+        .split("\n")
+        .map((line) => line.replace(/\s+$/, ""))
+        .filter((line) => line.length > 0);
+}
+/** Notion's per-`rich_text`-object content cap. A longer line is split across several objects,
+ *  which `renderRich` re-joins with no separator — so the split is invisible on the way back. */
+const MAX_RICH_TEXT = 2000;
+/** The wire shape for a plain, unannotated string: `text.content`, which {@link renderBlocks}
+ *  reads back through its `rt.text?.content` fallback. */
+function plainRich(content) {
+    if (content.length === 0)
+        return [];
+    const out = [];
+    for (let i = 0; i < content.length; i += MAX_RICH_TEXT) {
+        out.push({ type: "text", text: { content: content.slice(i, i + MAX_RICH_TEXT) } });
+    }
+    return out;
+}
+function mkBlock(type, payload) {
+    return { object: "block", type, [type]: payload };
+}
+/** One markdown line → the block Notion should store for it. */
+function blockForLine(line) {
+    let m;
+    if ((m = line.match(/^### (.*)$/)))
+        return mkBlock("heading_3", { rich_text: plainRich(m[1]) });
+    if ((m = line.match(/^## (.*)$/)))
+        return mkBlock("heading_2", { rich_text: plainRich(m[1]) });
+    if ((m = line.match(/^# (.*)$/)))
+        return mkBlock("heading_1", { rich_text: plainRich(m[1]) });
+    // Exactly the two markers `renderBlocks` emits. `- [X] x` deliberately does NOT match: Notion has
+    // no capital-X to-do state, so storing it as one would read back as `- [x] x`. It falls through to
+    // the paragraph arm below, which keeps the line verbatim.
+    if ((m = line.match(/^- \[([ x])\] (.*)$/))) {
+        return mkBlock("to_do", { rich_text: plainRich(m[2]), checked: m[1] === "x" });
+    }
+    if ((m = line.match(/^- (.*)$/)))
+        return mkBlock("bulleted_list_item", { rich_text: plainRich(m[1]) });
+    if ((m = line.match(/^1\. (.*)$/)))
+        return mkBlock("numbered_list_item", { rich_text: plainRich(m[1]) });
+    if ((m = line.match(/^> (.*)$/)))
+        return mkBlock("quote", { rich_text: plainRich(m[1]) });
+    if (line === "---")
+        return mkBlock("divider", {});
+    // Everything else — including an indented list line, a code fence and a rich-block placeholder —
+    // becomes a paragraph carrying the line VERBATIM. `renderBlocks` renders a top-level paragraph as
+    // its own text, so the markdown reads back unchanged even where the Notion block type is coarser.
+    return mkBlock("paragraph", { rich_text: plainRich(line) });
+}
+/**
+ * Markdown lines → the blocks Notion's block-append API takes, PROVEN to read back unchanged.
+ *
+ * 🔴 THE ROUND-TRIP CHECK IS THE CONTRACT, not a nicety. Memory that reads back different from what
+ * was written is silent corruption of the agent's own learned facts, and it would surface a whole
+ * session later as a mangled memory file with no error anywhere. So the blocks are rendered back
+ * through {@link renderBlocks} and any difference THROWS — the write is refused rather than landed.
+ *
+ * `lines` must already be {@link contentLines} output (no blank lines, no trailing whitespace).
+ *
+ * THE ANCHOR BLOCK is why the check renders one extra line and drops it. `renderBlocks` trims the
+ * whole document's edges, which would eat the leading indent of an INDENTED FIRST LINE (a nested
+ * bullet is a normal thing to append) and report a false difference. An appended batch is never the
+ * document's first line in reality — it lands after the page's existing blocks — so the check
+ * renders it in that position. The one case where reality matches the trim is an append onto an
+ * EMPTY page: there an indented first line does come back de-indented, and the NEXT write refuses
+ * loudly rather than papering over it.
+ */
+export function blocksFromMarkdown(lines) {
+    const blocks = lines.map(blockForLine);
+    const anchor = mkBlock("paragraph", { rich_text: plainRich("anchor") });
+    const back = contentLines(renderBlocks([anchor, ...blocks])).slice(1);
+    const at = back.findIndex((line, i) => line !== lines[i]);
+    if (back.length !== lines.length || at !== -1) {
+        const i = at === -1 ? Math.min(back.length, lines.length) : at;
+        throw new Error(`notion memory: line ${i + 1} cannot be stored as a Notion block without changing it ` +
+            `(would read back as ${JSON.stringify(back[i] ?? "(nothing)")}, not ${JSON.stringify(lines[i] ?? "(nothing)")}). ` +
+            `The write is refused rather than saved in a form the next read would report differently.`);
+    }
+    return blocks;
+}
+/** The title of a child_page / child_database block (for the memory file path). */
+export function pageTitle(block) {
+    const cp = (block.child_page ?? block.child_database);
+    return cp?.title?.trim() || "untitled";
+}
+//# sourceMappingURL=blocks.js.map

package/dist/agent/memory/blocks.js.map

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

package/dist/agent/memory/memory.d.ts

@@ -0,0 +1,157 @@
+import { type MemoryProvider, type MemoryAccess, type MemorySilo, type CredentialEndpointRules, type RetryPolicy } from "@open-everywhere/core/agent/adapter-api.js";
+import { type BlockNode } from "./blocks.js";
+/**
+ * The ORG-DEFAULT memory credential id — the ROLE a domain override replaces, and the role name a
+ * `credentials` binding must name (`{ connector: "notion", credential: "memory", use: "<id>" }`).
+ *
+ * It is a SEPARATE role from the channel plumbing key on purpose. An operator may share a domain's
+ * BRAIN page tree with one integration and its WORK pages with another, and `Domain.credentials` is
+ * keyed on the role exactly so that stays expressible.
+ */
+export declare const NOTION_MEMORY_CREDENTIAL = "memory";
+export type HttpFetch = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+/** Minimal Notion REST client — lists a block's children (paginated) and appends new ones.
+ *
+ * `endpoints` (OPE-505) is the credential's declared endpoint narrowing, carried alongside the
+ * token so the fence travels with it — see {@link resolveNotionMemoryCredential}, the ONLY
+ * resolver, which returns the pair rather than a bare token for exactly this reason.
+ *
+ * 429/`Retry-After` BACKOFF (OPE-1255): `children` honours a 429 through `withRetryAfterLoose` —
+ * the same shared primitive `channels/notion-api.ts`'s `notionFetch` uses, adapted for `HttpFetch`'s
+ * response shape, which carries no `headers` accessor of its own. This was the ONE Notion transport
+ * OPE-1233 left uncovered — see `docs/extending/provider-rate-limits.md`. */
+export declare class NotionClient {
+    private readonly token;
+    private readonly apiBase;
+    /** Tightens or drives the 429 backoff (OPE-1255) — a test injects a stub `sleep`; omitted
+     *  takes the shared defaults from `channels/rate-limit-retry.ts`. */
+    private readonly retry?;
+    private readonly fetchFn;
+    constructor(token: string, fetchFn?: HttpFetch, apiBase?: string, endpoints?: CredentialEndpointRules, 
+    /** Tightens or drives the 429 backoff (OPE-1255) — a test injects a stub `sleep`; omitted
+     *  takes the shared defaults from `channels/rate-limit-retry.ts`. */
+    retry?: RetryPolicy | undefined);
+    children(blockId: string): Promise<BlockNode[]>;
+    /**
+     * APPEND blocks to the end of a page (or of any block that takes children) — Notion's own
+     * `PATCH /v1/blocks/{id}/children`, the write half of this backing (OPE-70).
+     *
+     * It rides the SAME guarded fetch the read does, so a credential narrowed to `GET` refuses the
+     * append before it is dispatched, and it carries the same 429 backoff. Batched at Notion's
+     * 100-children cap; a batch that fails THROWS, so a partial append surfaces as a failed persist
+     * rather than a success line over lost bytes.
+     */
+    appendChildren(blockId: string, children: readonly BlockNode[]): Promise<void>;
+}
+export interface NotionMemoryDeps {
+    /**
+     * WHICH Notion integration a read runs under, from the calling domain (OPE-485). Pure and
+     * synchronous, because it is also half the cache key. Omitted ⇒ every read uses the org default.
+     */
+    credentialFor?(access?: MemoryAccess): string;
+    client(silo: MemorySilo, credentialId: string): NotionClient | Promise<NotionClient>;
+}
+/**
+ * Build the Notion memory provider. `deps.client(silo, credentialId)` yields a client for a silo
+ * under one integration's token. Reads are cached for TTL_MS — a curated baseline changes rarely,
+ * and the subtree pull is several API calls.
+ *
+ * 🔴 THE CACHE KEY CARRIES THE CREDENTIAL AND THE SELECTION, never the root page alone. Two
+ * integrations may both be shared a page and see DIFFERENT subtrees of it, because Notion shares per
+ * page tree; and two silos may name one page under one integration and select different subsets of
+ * it. Keying on the page alone let the first reader's files serve the second — the cross-domain read
+ * the per-domain credential exists to prevent, and the subset leak `recursive`/`select` exists to
+ * prevent. See {@link cacheKeyFor}.
+ */
+export declare function makeNotionProvider(deps: NotionMemoryDeps): MemoryProvider;
+/**
+ * One resolved Notion memory credential: the token to call with, PAIRED WITH the endpoint rules
+ * (OPE-505) that token may be used inside. Build it with {@link resolveNotionMemoryCredential} —
+ * spread into a {@link NotionClient} constructor call, never assembled by hand.
+ *
+ * 🔴 THERE IS DELIBERATELY NO TOKEN-ONLY RESOLVER. A caller holding a bare token can only build an
+ * UNFENCED `NotionClient` (`guardHttpFetch` returns the base fetch by identity when handed no
+ * rules), so a resolver that returned the string alone would silently disable the check on
+ * whichever call site used it — the same failure mode `notion-api.ts`'s `resolveNotionCredential`
+ * exists to close on the channel-plumbing path.
+ */
+export interface ResolvedNotionMemoryCredential {
+    readonly token: string;
+    /** The credential's declared endpoint narrowing, or undefined when it declares none. */
+    readonly endpoints?: CredentialEndpointRules;
+}
+/**
+ * The Notion credential ONE memory read runs under — the org default, or a bound domain's own
+ * integration — together with its endpoint rules. THE ONLY way to resolve a Notion memory
+ * credential.
+ *
+ * TWO PATHS, and the difference is the whole rule (OPE-467, applied to memory by OPE-485):
+ *   • `credentialId` IS the org-default role ⇒ the deployment key, resolved through the explicit
+ *     broker + ref stamp `registerNotionMemory` carries. Unchanged behaviour for every deployment
+ *     that binds nothing, which is nearly all of them. Its endpoint rules come from the SAME-named
+ *     `"memory"` entry in the registered provider set (agent/access/providers.ts) — that entry's
+ *     `secretRef` is not what this path reads (see the comment there), but its `endpoints` is, so
+ *     the org-default read is narrowed exactly as the entry declares.
+ *   • `credentialId` is a BOUND domain's own credential ⇒ that `ConnectorCredential`'s own
+ *     `secretRef` + `broker` + `endpoints`, resolved through the same seam `channels/notion-api.ts`
+ *     uses.
+ *
+ * 🔴 A BOUND DOMAIN NEVER FALLS BACK TO THE ORG KEY. When the named credential is absent from the
+ * provider set, or carries no `secretRef`, this THROWS. Quietly serving the deployment key there
+ * would hand the domain the exact integration it was bound away from, which is the isolation the
+ * binding was created to buy. `assertDomainCredentialsResolvable` already refuses such a config at
+ * boot, so this throw is the second line, not the first.
+ */
+export declare function resolveNotionMemoryCredential(credentialId: string, broker: string, secretRef: string): Promise<ResolvedNotionMemoryCredential>;
+/**
+ * THE PRODUCTION WIRING of the credential seam, as a value — the deps {@link registerNotionMemory}
+ * registers. It is exported so a test drives the REAL wiring with only the HTTP call replaced,
+ * rather than restating `credentialFor` and getting a green from its own copy of the rule.
+ *
+ * `fetchFn` is the ONLY injected part. Leave it undefined in production and `NotionClient` uses
+ * `globalThis.fetch`.
+ */
+export declare function notionMemoryDeps(secretRef: string, broker: string, fetchFn?: HttpFetch): NotionMemoryDeps;
+/**
+ * Register the Notion memory backing, and DECLARE it as a connector-owned memory capability
+ * (OPE-390) so the prefetch invariant applies: a domain may only project a Notion subtree if it
+ * holds the `notion` connector grant. Memory rides the same route as connector access.
+ *
+ * MODE `"materialise"` — the DEFAULT posture: the files are a read-only PROJECTION, not the source
+ * of truth. The subtree is pulled to Markdown, chmod-locked in the sandbox, and the banner routes
+ * writes to Notion's own connector ops. A silo the author declares WRITABLE opts out of that
+ * posture per silo and persists through the append path above (OPE-70); the mode names what a
+ * Notion silo is unless its author says otherwise, and it stays the recommended shape.
+ *
+ * SUBJECT `"app-principal"` — structurally pinned (memory/connector-memory.ts). Materialisation is
+ * host-side at session.started, outside any session and any approval flow, and a shared domain
+ * brain must never be projected through one person's user-subject OAuth token: doing so would bake
+ * their personal access into a cache every session in the domain then reads.
+ *
+ * CREDENTIAL (OPE-485, completing the symmetry ruling's credential half). The domain that OWNS the
+ * silo picks the integration, and a domain that binds none uses the org default — the same one rule
+ * `channels/notion-credentials.ts` states for the channel plane. The seam that carries the domain is
+ * `MemoryAccess` (core `memory/provider.ts`); this backing turns it into a credential id with
+ * `domainCredentialId(access.domain, "notion", "memory")`.
+ *
+ * The ORG DEFAULT still resolves through its explicit home credential BROKER (`getSecretVia`) —
+ * `"db"` + `db:notion:memory` (OPE-408 step 2, re-stamped from `"env"` + `NOTION_TOKEN`),
+ * overridable via `OE_NOTION_SECRET_BROKER`/`OE_NOTION_SECRET_REF`. A BOUND domain resolves its own
+ * `ConnectorCredential` instead, through the same `findConnectorCredential` → `getSecretVia` seam the
+ * channel key uses, and FAILS CLOSED — see {@link resolveNotionMemoryCredential}.
+ *
+ * Resolution stays LAZY (per read, inside makeNotionProvider's client factory): registering is cheap
+ * and side-effect-free, and a missing secret fails loud at read time only when a `notion` silo is
+ * actually used.
+ */
+export declare function registerNotionMemory(secretRef?: string, broker?: string): void;
+//# sourceMappingURL=memory.d.ts.map

package/dist/agent/memory/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../../agent/memory/memory.ts"],"names":[],"mappings":"AAqCA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,YAAY,EAQjB,KAAK,UAAU,EAOf,KAAK,uBAAuB,EAE5B,KAAK,WAAW,EACjB,MAAM,4CAA4C,CAAC;AAGpD,OAAO,EAML,KAAK,SAAS,EAGf,MAAM,aAAa,CAAC;AAQrB;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,WAAW,CAAC;AAQjD,MAAM,MAAM,SAAS,GAAG,CACtB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KACrE,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAAC,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,CAAC;AA4BjG;;;;;;;;;6EAS6E;AAC7E,qBAAa,YAAY;IAIrB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB;yEACqE;IACrE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;IATzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IAEpC,YACmB,KAAK,EAAE,MAAM,EAC9B,OAAO,GAAE,SAAoD,EAC5C,OAAO,GAAE,MAAY,EACtC,SAAS,CAAC,EAAE,uBAAuB;IACnC;yEACqE;IACpD,KAAK,CAAC,EAAE,WAAW,YAAA,EAGrC;IAEK,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAuBpD;IAED;;;;;;;;OAQG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,SAAS,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAmBnF;CACF;AAmFD,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,aAAa,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,MAAM,CAAC;IAC9C,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACtF;AAkBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,cAAc,CA2KzE;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,6BAA6B,CACjD,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,8BAA8B,CAAC,CAczC;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,GAAG,gBAAgB,CAQzG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,SAAyD,EAClE,MAAM,SAA8C,GACnD,IAAI,CAaN"}