@legioncodeinc/nectar 0.0.1

package/dist/source-graph/deeplake-credentials.js

@@ -0,0 +1,109 @@
+/**
+ * Deep Lake credentials loader for hivenectar (PRD-005).
+ *
+ * Reads the SHARED `~/.deeplake/credentials.json` file that `hivemind login`
+ * (and honeycomb) already write, mirroring the shape honeycomb's
+ * `loadDiskCredentials` / `deeplakeCredentialsFileProvider`
+ * (`src/daemon/runtime/auth/credentials-store.ts`,
+ * `src/daemon/storage/config.ts`) read: `{ apiUrl, token, orgId, workspaceId }`.
+ * Per ADR-0002, hivenectar never imports honeycomb's runtime for this; it
+ * reads the same on-disk file with its own loader.
+ *
+ * Fail-closed by design (mirrors honeycomb's `StorageConfigError` posture): a
+ * missing file, malformed JSON, or a missing required field throws a
+ * `DeepLakeCredentialsError` listing exactly what is wrong, rather than
+ * returning a partially-undefined credential object a caller could
+ * accidentally use. `apiUrl` is the one field with a documented default (a
+ * legacy or hand-written file may omit it); `token`, `orgId`, and
+ * `workspaceId` are load-bearing and always required.
+ *
+ * The token is never logged or included in an error message in full;
+ * `redactToken` keeps only the last 4 characters, exactly like honeycomb's
+ * `redactToken` (`src/daemon/runtime/auth/credentials-store.ts:254-257`, its
+ * `defaultCredentialProvider` variant).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** The SHARED credentials directory name under the user's home. */
+export const CREDENTIALS_DIR_NAME = ".deeplake";
+/** The credentials file name within the dir. */
+export const CREDENTIALS_FILE_NAME = "credentials.json";
+/** The canonical Deep Lake API base URL used when a file omits `apiUrl`. */
+export const DEFAULT_DEEPLAKE_API_URL = "https://api.deeplake.ai";
+/**
+ * Structured, fail-closed rejection. Carries exactly which fields were missing
+ * or invalid so a caller (or an operator reading a log line) knows what to
+ * fix without the loader ever echoing the file's contents (which may hold the
+ * token).
+ */
+export class DeepLakeCredentialsError extends Error {
+    missing;
+    constructor(missing) {
+        super(`Invalid Deep Lake credentials: ${missing.join("; ")}`);
+        this.name = "DeepLakeCredentialsError";
+        this.missing = missing;
+    }
+}
+/** Resolve the credentials directory, honoring the test override. */
+export function credentialsDir(options = {}) {
+    return options.dir ?? join(homedir(), CREDENTIALS_DIR_NAME);
+}
+/** Resolve the full credentials file path within the (possibly overridden) dir. */
+export function credentialsPath(options = {}) {
+    return join(credentialsDir(options), CREDENTIALS_FILE_NAME);
+}
+/**
+ * Load and validate `~/.deeplake/credentials.json` (or the overridden dir in
+ * `options.dir`). Throws {@link DeepLakeCredentialsError} listing every
+ * problem found: a missing file, invalid JSON, a non-object payload, or a
+ * missing/empty `token` / `orgId` / `workspaceId`. Never returns a partial
+ * credential — the caller either gets a fully-populated `DeepLakeCredentials`
+ * or a clear, typed reason it could not.
+ */
+export function loadDeepLakeCredentials(options = {}) {
+    const path = credentialsPath(options);
+    if (!existsSync(path)) {
+        throw new DeepLakeCredentialsError([`credentials file not found at ${path}`]);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new DeepLakeCredentialsError([`credentials file at ${path} is not valid JSON`]);
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new DeepLakeCredentialsError([`credentials file at ${path} does not contain a JSON object`]);
+    }
+    const record = parsed;
+    const missing = [];
+    if (typeof record.token !== "string" || record.token.length === 0)
+        missing.push("token");
+    if (typeof record.orgId !== "string" || record.orgId.length === 0)
+        missing.push("orgId");
+    if (typeof record.workspaceId !== "string" || record.workspaceId.length === 0)
+        missing.push("workspaceId");
+    if (missing.length > 0) {
+        throw new DeepLakeCredentialsError(missing);
+    }
+    const apiUrl = typeof record.apiUrl === "string" && record.apiUrl.length > 0 ? record.apiUrl : DEFAULT_DEEPLAKE_API_URL;
+    return {
+        apiUrl,
+        token: record.token,
+        orgId: record.orgId,
+        workspaceId: record.workspaceId,
+    };
+}
+/**
+ * Redact a token for logs and errors. Never echoes a token in full: keeps the
+ * last 4 chars for correlation, masks the rest. An empty/short value collapses
+ * to a fixed mask so length isn't leaked either. Mirrors honeycomb's
+ * `redactToken` (`src/daemon/runtime/auth/credentials-store.ts:254-257`).
+ */
+export function redactToken(value) {
+    if (value.length <= 4)
+        return "****";
+    return `****${value.slice(-4)}`;
+}
+//# sourceMappingURL=deeplake-credentials.js.map

package/dist/source-graph/deeplake-credentials.js.map

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

package/dist/source-graph/deeplake-heal.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Heal-on-first-write for the Deep Lake adapter (PRD-005).
+ *
+ * Mirrors the missing-table branch of honeycomb's `withHeal`
+ * (`src/daemon/storage/heal.ts:286-313`), scoped down to what the
+ * source-graph tables need: a write that fails because its table does not
+ * exist yet triggers exactly ONE create-then-retry. Any other failure
+ * (permission, connection, timeout, a genuine syntax error) propagates
+ * unchanged and never triggers a create — the same anti-mask rule honeycomb's
+ * `classifyFailure` documents: a credentials or syntax problem must never be
+ * misread as a schema gap behind a confusing CREATE attempt.
+ *
+ * Column healing (honeycomb's `healColumns` / `ALTER TABLE ADD COLUMN`) is
+ * deliberately NOT ported here: `SOURCE_GRAPH_COLUMNS` /
+ * `SOURCE_GRAPH_VERSIONS_COLUMNS` are the full, fixed column set at CREATE
+ * time and PRD-005 does not add columns to an already-created table out from
+ * under a running adapter, so there is no missing-column case for this
+ * adapter to heal. A future PRD that adds a column to the catalog would need
+ * to bring the column-heal half of honeycomb's engine over too.
+ */
+import type { CatalogTable } from "./schema.js";
+import type { DeepLakeRow } from "./deeplake-transport.js";
+import { TransportError } from "./deeplake-transport.js";
+/**
+ * The minimal shape `withHeal` needs from a transport: one method that runs a
+ * SQL statement. `HttpDeepLakeTransport` satisfies this structurally (its
+ * `query` method is public even though its connection fields are private), so
+ * production callers pass it directly; a test can pass a plain fake object
+ * with a `query` method instead, without needing to construct a real
+ * `HttpDeepLakeTransport` or reach for a mocking library (hivenectar has
+ * none, by design).
+ */
+export interface QueryRunner {
+    query(sql: string): Promise<DeepLakeRow[]>;
+}
+/**
+ * Classify a `query`-kind `TransportError` message as a missing-table failure
+ * (mirrors honeycomb's `classifyFailure`, `src/daemon/storage/heal.ts:77-98`,
+ * missing-table branch only). Auth/permission failures are excluded first so a
+ * message that happens to mention a relation is never misread as a schema gap.
+ */
+export declare function isMissingTableError(err: TransportError): boolean;
+/**
+ * Run a write, and on a missing-table failure, CREATE the table and retry the
+ * write EXACTLY ONCE. Any other failure (or a success) returns/throws
+ * immediately and unhealed. A second failure after the heal propagates
+ * without a further retry (no infinite loop).
+ *
+ * `runWrite` is the original statement's thunk so the retry re-issues the
+ * identical write.
+ */
+export declare function withHeal(transport: QueryRunner, table: CatalogTable, runWrite: () => Promise<DeepLakeRow[]>): Promise<DeepLakeRow[]>;
+//# sourceMappingURL=deeplake-heal.d.ts.map

package/dist/source-graph/deeplake-heal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplake-heal.d.ts","sourceRoot":"","sources":["../../src/source-graph/deeplake-heal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;CAC5C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAQhE;AAED;;;;;;;;GAQG;AACH,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,WAAW,EACtB,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC,GACrC,OAAO,CAAC,WAAW,EAAE,CAAC,CAaxB"}

package/dist/source-graph/deeplake-heal.js

@@ -0,0 +1,41 @@
+import { buildCreateTableSql } from "./schema.js";
+import { TransportError } from "./deeplake-transport.js";
+/**
+ * Classify a `query`-kind `TransportError` message as a missing-table failure
+ * (mirrors honeycomb's `classifyFailure`, `src/daemon/storage/heal.ts:77-98`,
+ * missing-table branch only). Auth/permission failures are excluded first so a
+ * message that happens to mention a relation is never misread as a schema gap.
+ */
+export function isMissingTableError(err) {
+    if (err.kind !== "query")
+        return false;
+    if (/permission denied|must be owner|not authorized|forbidden|unauthorized/i.test(err.message)) {
+        return false;
+    }
+    return /table does not exist|relation ["']?[A-Za-z_][A-Za-z0-9_.]*["']? does not exist|no such table/i.test(err.message);
+}
+/**
+ * Run a write, and on a missing-table failure, CREATE the table and retry the
+ * write EXACTLY ONCE. Any other failure (or a success) returns/throws
+ * immediately and unhealed. A second failure after the heal propagates
+ * without a further retry (no infinite loop).
+ *
+ * `runWrite` is the original statement's thunk so the retry re-issues the
+ * identical write.
+ */
+export async function withHeal(transport, table, runWrite) {
+    try {
+        return await runWrite();
+    }
+    catch (err) {
+        if (!(err instanceof TransportError) || !isMissingTableError(err)) {
+            throw err;
+        }
+        // Missing table: create it (IF NOT EXISTS makes concurrent heals
+        // converge), then retry the original write exactly once. Any failure from
+        // here on (the create itself, or the retried write) propagates unchanged.
+        await transport.query(buildCreateTableSql(table));
+        return runWrite();
+    }
+}
+//# sourceMappingURL=deeplake-heal.js.map

package/dist/source-graph/deeplake-heal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplake-heal.js","sourceRoot":"","sources":["../../src/source-graph/deeplake-heal.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAezD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAmB;IACrD,IAAI,GAAG,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,wEAAwE,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/F,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,+FAA+F,CAAC,IAAI,CACzG,GAAG,CAAC,OAAO,CACZ,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,SAAsB,EACtB,KAAmB,EACnB,QAAsC;IAEtC,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,GAAG,YAAY,cAAc,CAAC,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;YAClE,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,iEAAiE;QACjE,0EAA0E;QAC1E,0EAA0E;QAC1E,MAAM,SAAS,CAAC,KAAK,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,OAAO,QAAQ,EAAE,CAAC;IACpB,CAAC;AACH,CAAC"}

package/dist/source-graph/deeplake-store.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The Deep Lake-backed SourceGraphStore adapter (PRD-005).
+ *
+ * `DeepLakeSourceGraphStore` is the durable substrate for the two source-graph
+ * tables (`source_graph`, `source_graph_versions`), reached over the network
+ * through hivenectar's own transport (`deeplake-transport.ts`) per ADR-0002 -
+ * never by importing the honeycomb runtime in-process. It is an ADDITIONAL
+ * adapter alongside `InMemorySourceGraphStore` (`memory-store.ts`), not a
+ * replacement of it: the in-memory store keeps backing the file-registration
+ * ladder's tests and local dev, unchanged.
+ *
+ * `DeepLakeSourceGraphStore implements AsyncSourceGraphStore`
+ * (`store.ts`), not the synchronous `SourceGraphStore`. See the docblock on
+ * `AsyncSourceGraphStore` for why: the ladder's synchronous contract cannot be
+ * honored by a store that does real HTTP I/O, and wiring the ladder to an
+ * async store is a future PRD's decision, not this adapter's.
+ *
+ * All reads are scoped by `org_id`/`workspace_id`/`project_id` wherever the
+ * method receives a `Tenancy` (`listLatestVersions`, `latestVersionByPath`,
+ * `latestVersionByHash`), per PRD-005c's soft-filter contract - the
+ * `project_id` predicate is never omitted from those queries. The four
+ * by-nectar-only methods (`getIdentity`, `touchIdentity`, `nextSeq`,
+ * `latestVersion`) take no `Tenancy` parameter in the `SourceGraphStore` /
+ * `AsyncSourceGraphStore` seam itself - `nectar` is a globally-unique 26-char
+ * ULID (`ulid.ts`) and `InMemorySourceGraphStore` looks those up by nectar
+ * alone too (no tenancy filter), so this adapter matches that seam exactly
+ * for drop-in-replacement parity rather than inventing extra scoping the
+ * interface does not carry.
+ */
+import type { SourceGraphRow, SourceGraphVersionRow, Tenancy } from "./model.js";
+import type { AsyncSourceGraphStore, LatestVersion } from "./store.js";
+import type { DeepLakeCredentials } from "./deeplake-credentials.js";
+import type { QueryRunner } from "./deeplake-heal.js";
+/** Options for {@link DeepLakeSourceGraphStore}. */
+export interface DeepLakeSourceGraphStoreOptions {
+    /** Loaded via `deeplake-credentials.ts#loadDeepLakeCredentials`. */
+    readonly credentials: DeepLakeCredentials;
+    /** Per-statement timeout override in ms; see `DEFAULT_TRANSPORT_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+    /**
+     * TEST-ONLY SEAM: inject a fake `QueryRunner` instead of constructing a
+     * real `HttpDeepLakeTransport` from `credentials`. When absent (the
+     * production path, and the default for every existing caller), the
+     * constructor builds a real `HttpDeepLakeTransport` from `credentials`
+     * exactly as before this option existed. `credentials` is still required
+     * even when `transport` is supplied (a test passes a trivial placeholder
+     * object; nothing in the class reads `credentials` again once the
+     * transport is constructed), which keeps this a strict addition rather
+     * than a change to the required shape of the options object.
+     */
+    readonly transport?: QueryRunner;
+}
+export declare class DeepLakeSourceGraphStore implements AsyncSourceGraphStore {
+    private readonly transport;
+    constructor(options: DeepLakeSourceGraphStoreOptions);
+    /**
+     * Run a READ statement, tolerating a missing-table failure as "no data yet"
+     * (an empty result), exactly like honeycomb's read-path guard
+     * (`tableExists`, `src/daemon/storage/heal.ts:171-175`) fails OPEN rather
+     * than provoking a CREATE. Only the missing-table shape is tolerated; a
+     * genuine connection/timeout/permission/syntax failure still propagates.
+     * Reads never create a table - only a write does, via `withHeal`.
+     */
+    private readTolerant;
+    /**
+     * Insert-only mint, mirroring honeycomb's SELECT-before-INSERT write
+     * pattern (`selectBeforeInsert`, `src/daemon/storage/writes.ts:325-360`)
+     * rather than relying on a Deep Lake UNIQUE constraint: the Deep Lake SQL
+     * surface this adapter targets has no reliably-enforced uniqueness
+     * constraint to lean on, so "does the nectar already exist" is answered by
+     * probing first. Both the probe and the insert are heal-aware (a fresh
+     * tenancy's tables may not exist yet).
+     *
+     * After the insert, a best-effort re-verify SELECT counts the rows for the
+     * nectar; more than one means a race doubled it. Deep Lake offers no
+     * transactions, so this cannot PREVENT a race, only make it observable
+     * (the same limitation honeycomb documents). In practice a real race here
+     * is a near-zero-probability event - a nectar is a 26-char ULID with 80
+     * bits of randomness (`ulid.ts`), not a narrow key space two writers could
+     * plausibly collide on - so a failure of the re-verify SELECT itself
+     * (e.g. a transient network hiccup immediately after a successful insert)
+     * does not fail the whole call; the insert already succeeded and the
+     * re-verify is an observability nicety, not the source of truth.
+     */
+    insertIdentity(row: SourceGraphRow): Promise<void>;
+    getIdentity(nectar: string): Promise<SourceGraphRow | undefined>;
+    /**
+     * Bump `last_update_date` via an in-place `UPDATE`.
+     *
+     * KNOWN CAVEAT: honeycomb's own operational history found that an in-place
+     * `UPDATE ... WHERE id = ...` does not reliably land on this backend under
+     * load - a by-id point read can still return a pre-update snapshot from a
+     * stale segment (see honeycomb `src/daemon/storage/catalog/tenancy.ts:475-489`,
+     * where the equivalent revoke-by-UPDATE was RETIRED in favor of an
+     * append-only version-bump for that reason). `source_graph`'s catalog entry
+     * (`schema.ts`) nonetheless declares `writePattern: "update-or-insert"` for
+     * this exact field, and `last_update_date` is a low-stakes denormalized
+     * "last observed change" timestamp (not an authorization-bearing flag like
+     * the retired revoke), so this adapter uses `UPDATE` as declared rather than
+     * inventing an append-based scheme the schema does not define. If
+     * `last_update_date` staleness proves to be a real problem in practice, a
+     * future PRD should revisit this the same way honeycomb did - not this
+     * adapter, which mirrors the declared write pattern faithfully.
+     */
+    touchIdentity(nectar: string, lastUpdateDate: string): Promise<void>;
+    appendVersion(row: SourceGraphVersionRow): Promise<void>;
+    /**
+     * The next monotonic seq for a nectar: MAX(seq)+1 over every version row,
+     * computed client-side by {@link reduceLatestVersion} rather than trusted
+     * to an SQL `ORDER BY`/`LIMIT`/`MAX()` clause. See that function's docblock
+     * for why.
+     */
+    nextSeq(nectar: string): Promise<number>;
+    /** The latest (MAX seq) version row for a nectar; see {@link reduceLatestVersion}. */
+    latestVersion(nectar: string): Promise<SourceGraphVersionRow | undefined>;
+    /**
+     * Every nectar's latest version, scoped by the full tenancy predicate
+     * (`org_id`/`workspace_id`/`project_id`, PRD-005c). Fetches every identity
+     * and every version row for the tenancy and reduces to "latest per nectar"
+     * in application code, mirroring `InMemorySourceGraphStore.listLatestVersions`'s
+     * iterate-and-reduce shape rather than pushing a `GROUP BY`/window-function
+     * reduction into SQL. This is not optimized for a very large per-tenant
+     * row count; a future PRD could push the "latest per nectar" reduction into
+     * SQL if that becomes the bottleneck. It is not this adapter's job to
+     * diverge from the reference in-memory implementation's behavior to chase
+     * that optimization prematurely.
+     */
+    listLatestVersions(tenancy: Tenancy): Promise<LatestVersion[]>;
+    latestVersionByPath(tenancy: Tenancy, path: string): Promise<LatestVersion | undefined>;
+    latestVersionByHash(tenancy: Tenancy, contentHash: string): Promise<LatestVersion | undefined>;
+    /**
+     * Delete a nectar (identity + versions) scoped to `tenancy`, the SOLE deletion
+     * path (`prune --confirm`, PRD-006d). Both DELETE statements carry the full
+     * tenancy predicate (`org_id`/`workspace_id`/`project_id`, never omitting
+     * `project_id`) alongside the nectar key, so a nectar minted under another
+     * project is never removed by a delete issued in this tenancy (AC-20).
+     *
+     * The delete path deliberately does NOT go through `withHeal`: a missing table
+     * means there is nothing to delete, so it is a harmless no-op, NOT a reason to
+     * CREATE a fresh (empty) table. `deleteTolerant` therefore swallows only the
+     * missing-table transport error (via `isMissingTableError`, the same
+     * classification the read path uses) and lets every other failure propagate.
+     */
+    deleteNectar(tenancy: Tenancy, nectar: string): Promise<void>;
+    /**
+     * Run a DELETE, tolerating a missing-table failure as "nothing to delete" (a
+     * no-op). Never creates a table. Any other transport failure propagates.
+     */
+    private deleteTolerant;
+}
+//# sourceMappingURL=deeplake-store.d.ts.map

package/dist/source-graph/deeplake-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deeplake-store.d.ts","sourceRoot":"","sources":["../../src/source-graph/deeplake-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EAAkB,cAAc,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEjG,OAAO,KAAK,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGrE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAOtD,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,oEAAoE;IACpE,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC;IAC1C,gFAAgF;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,WAAW,CAAC;CAClC;AAyLD,qBAAa,wBAAyB,YAAW,qBAAqB;IACpE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,OAAO,EAAE,+BAA+B;IAYpD;;;;;;;OAOG;YACW,YAAY;IAS1B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,cAAc,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBlD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAMtE;;;;;;;;;;;;;;;;;OAiBG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpE,aAAa,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAK9D;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAY9C,sFAAsF;IAChF,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,SAAS,CAAC;IAM/E;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IA8B9D,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAKvF,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC;IAKpG;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWnE;;;OAGG;YACW,cAAc;CAQ7B"}