@struktoai/mirage-node 0.0.5 → 0.0.6

package/dist/core/hf_hub/commit.js

@@ -0,0 +1,124 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { apiUrl, hubPost, hubPostNdjson, revSegment } from "./client.js";
+import { COMMIT_CHUNK, DEFAULT_COMMIT_MESSAGE, PREUPLOAD_SAMPLE_BYTES } from "./constants.js";
+import { compareCodePoints } from '@struktoai/mirage-core/utils/sort';
+// The upload modes the Hub's preupload endpoint answers with. "regular" is a
+// git blob and rides inline in the commit; the other two are out-of-band
+// uploads that must happen BEFORE the commit references them.
+const REGULAR = 'regular';
+/**
+ * A write the Hub will only accept through the LFS/Xet upload path.
+ *
+ * Thrown rather than papered over, because the alternative is a commit that
+ * references content the Hub never received: the file would appear in the
+ * tree and every read of it would fail. Which files land here is the
+ * repository's own `.gitattributes` plus a size threshold, so it is the
+ * repo's decision, not a fixed byte count this code could apply.
+ */
+export class LfsRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'LfsRequiredError';
+    }
+}
+function b64(data) {
+    return Buffer.from(data).toString('base64');
+}
+/** The commit endpoint for one revision. */
+export function commitUrl(accessor, revision) {
+    const rev = revision ?? accessor.revision;
+    return apiUrl(accessor.endpoint, accessor.repoType, accessor.repoId, `/commit/${revSegment(rev)}`);
+}
+/**
+ * Ask the Hub how each file must be uploaded.
+ *
+ * The Hub decides regular-vs-LFS-vs-Xet from the repository's
+ * `.gitattributes` and the file's size, so it is asked rather than guessed. It
+ * only needs the first bytes to sniff the type, which is why a sample rather
+ * than the content is sent.
+ */
+export async function uploadModes(accessor, additions, revision) {
+    const modes = new Map();
+    if (additions.length === 0)
+        return modes;
+    const rev = revision ?? accessor.revision;
+    const url = apiUrl(accessor.endpoint, accessor.repoType, accessor.repoId, `/preupload/${revSegment(rev)}`);
+    for (let start = 0; start < additions.length; start += COMMIT_CHUNK) {
+        const chunk = additions.slice(start, start + COMMIT_CHUNK);
+        const body = {
+            files: chunk.map((add) => ({
+                path: add.path,
+                sample: b64(add.data.slice(0, PREUPLOAD_SAMPLE_BYTES)),
+                size: add.data.length,
+            })),
+        };
+        const data = await hubPost(accessor.token, url, body);
+        const rows = data.files;
+        for (const row of Array.isArray(rows) ? rows : []) {
+            if (typeof row !== 'object' || row === null)
+                continue;
+            const item = row;
+            modes.set(typeof item.path === 'string' ? item.path : '', typeof item.uploadMode === 'string' ? item.uploadMode : REGULAR);
+        }
+    }
+    return modes;
+}
+/**
+ * Serialize one commit as newline-delimited JSON.
+ *
+ * The header line comes first and carries the message; every operation is one
+ * line after it. This is the Hub's own shape, not a convention chosen here.
+ */
+export function payload(additions, deletions, folders, message, description = '', parent = '') {
+    const header = { summary: message, description };
+    if (parent !== '')
+        header.parentCommit = parent;
+    const lines = [{ key: 'header', value: header }];
+    for (const add of additions) {
+        lines.push({
+            key: 'file',
+            value: { content: b64(add.data), path: add.path, encoding: 'base64' },
+        });
+    }
+    for (const path of deletions)
+        lines.push({ key: 'deletedFile', value: { path } });
+    for (const path of folders)
+        lines.push({ key: 'deletedFolder', value: { path } });
+    return new TextEncoder().encode(lines.map((line) => `${JSON.stringify(line)}\n`).join(''));
+}
+/**
+ * Apply one commit to the repository.
+ *
+ * Every addition is checked against the preupload endpoint first, and a file
+ * the Hub wants uploaded out of band is refused here rather than referenced by
+ * a commit whose content never arrived.
+ */
+export async function commit(accessor, options = {}) {
+    const adds = options.additions ?? [];
+    const modes = await uploadModes(accessor, adds, options.revision);
+    const heavy = adds
+        .filter((add) => (modes.get(add.path) ?? REGULAR) !== REGULAR)
+        .map((add) => add.path)
+        .sort(compareCodePoints);
+    if (heavy.length > 0) {
+        throw new LfsRequiredError(`${accessor.repoId}: the Hub requires an LFS upload for ${heavy.join(', ')}; ` +
+            'write it with `hf upload` instead');
+    }
+    const body = payload(adds, options.deletions ?? [], options.folders ?? [], options.message ?? DEFAULT_COMMIT_MESSAGE, options.description ?? '');
+    const params = options.createPr === true ? { create_pr: '1' } : undefined;
+    const data = await hubPostNdjson(accessor.token, commitUrl(accessor, options.revision), body, params);
+    return typeof data === 'object' && data !== null ? data : {};
+}
+//# sourceMappingURL=commit.js.map

package/dist/core/hf_hub/commit.js.map

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

package/dist/core/hf_hub/config.d.ts

@@ -0,0 +1,18 @@
+import { z } from '@struktoai/mirage-core/resource/secrets';
+import type { ConfigOf } from '@struktoai/mirage-core/resource/secrets';
+/**
+ * What an `hf` install is configured with.
+ *
+ * An account CLI, so it declares this and reaches the Hub directly; it
+ * consults no mount. The token is optional because the Hub serves every
+ * public repository anonymously, and the verbs that need one (`auth whoami`,
+ * anything that writes) say so when it is missing rather than failing at the
+ * transport.
+ */
+export declare const HfConfigSchema: z.ZodObject<{
+    token: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type HfConfig = ConfigOf<typeof HfConfigSchema>;
+export declare function hfEndpoint(config: HfConfig): string;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/hf_hub/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/config.ts"],"names":[],"mappings":"AAcA,OAAO,EAAa,CAAC,EAAE,MAAM,yCAAyC,CAAA;AACtE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yCAAyC,CAAA;AAGvE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc;;;iBAGzB,CAAA;AAEF,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,cAAc,CAAC,CAAA;AAEtD,wBAAgB,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG,MAAM,CAGnD"}

package/dist/core/hf_hub/config.js

@@ -0,0 +1,33 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { secretStr, z } from '@struktoai/mirage-core/resource/secrets';
+import { API_BASE } from "./constants.js";
+/**
+ * What an `hf` install is configured with.
+ *
+ * An account CLI, so it declares this and reaches the Hub directly; it
+ * consults no mount. The token is optional because the Hub serves every
+ * public repository anonymously, and the verbs that need one (`auth whoami`,
+ * anything that writes) say so when it is missing rather than failing at the
+ * transport.
+ */
+export const HfConfigSchema = z.object({
+    token: secretStr().optional(),
+    endpoint: z.string().default(API_BASE),
+});
+export function hfEndpoint(config) {
+    const endpoint = config.endpoint;
+    return endpoint === '' ? API_BASE : endpoint;
+}
+//# sourceMappingURL=config.js.map

package/dist/core/hf_hub/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/core/hf_hub/config.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,yCAAyC,CAAA;AAEtE,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,KAAK,EAAE,SAAS,EAAE,CAAC,QAAQ,EAAE;IAC7B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC;CACvC,CAAC,CAAA;AAIF,MAAM,UAAU,UAAU,CAAC,MAAgB;IACzC,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAA;IAChC,OAAO,QAAQ,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAA;AAC9C,CAAC"}

package/dist/core/hf_hub/constants.d.ts

@@ -0,0 +1,18 @@
+export declare const API_BASE = "https://huggingface.co";
+export declare const DEFAULT_REVISION = "main";
+export declare const SCOPE_ERROR = 5000;
+export declare const TREE_PAGE_SIZE = 1000;
+export declare const TREE_PAGE_SIZE_EXPANDED = 100;
+export declare const MAX_TREE_PAGES = 1000;
+export declare const API_SEGMENTS: Record<string, string>;
+export declare const RESOLVE_SEGMENTS: Record<string, string>;
+export declare const PREUPLOAD_SAMPLE_BYTES = 512;
+export declare const HTTP_CONFLICT = 409;
+export declare const RETRY_STATUSES: Set<number>;
+export declare const MAX_RETRIES = 3;
+export declare const COMMIT_CHUNK = 256;
+export declare const MAX_DOWNLOAD_WORKERS = 8;
+export declare const REPO_ID_SEPARATOR = "--";
+export declare const GLOB_CHARS: readonly string[];
+export declare const DEFAULT_COMMIT_MESSAGE = "Update from mirage";
+//# sourceMappingURL=constants.d.ts.map

package/dist/core/hf_hub/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/constants.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,QAAQ,2BAA2B,CAAA;AAMhD,eAAO,MAAM,gBAAgB,SAAS,CAAA;AAEtC,eAAO,MAAM,WAAW,OAAO,CAAA;AAU/B,eAAO,MAAM,cAAc,OAAO,CAAA;AAClC,eAAO,MAAM,uBAAuB,MAAM,CAAA;AAK1C,eAAO,MAAM,cAAc,OAAO,CAAA;AAKlC,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAI/C,CAAA;AAMD,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAInD,CAAA;AAID,eAAO,MAAM,sBAAsB,MAAM,CAAA;AAOzC,eAAO,MAAM,aAAa,MAAM,CAAA;AAEhC,eAAO,MAAM,cAAc,aAAqC,CAAA;AAChE,eAAO,MAAM,WAAW,IAAI,CAAA;AAI5B,eAAO,MAAM,YAAY,MAAM,CAAA;AAK/B,eAAO,MAAM,oBAAoB,IAAI,CAAA;AAIrC,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAIrC,eAAO,MAAM,UAAU,EAAE,SAAS,MAAM,EAAoB,CAAA;AAK5D,eAAO,MAAM,sBAAsB,uBAAuB,CAAA"}

package/dist/core/hf_hub/constants.js

@@ -0,0 +1,80 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+export const API_BASE = 'https://huggingface.co';
+// The Hub's default branch. Unlike GitHub, where the default is per
+// repository and costs a request to learn, every Hub repo is created with
+// `main` and the API offers no way to change it, so an unpinned mount
+// resolves without a round trip.
+export const DEFAULT_REVISION = 'main';
+export const SCOPE_ERROR = 5000;
+// The tree endpoint's page size, and the reason there are two of them.
+// A bare listing serves up to 1000 rows a page. Asking for `expand=true`
+// -- the only way to learn the commit that last touched each path, which
+// is a Hub file's only mtime -- drops the server's own page to 50 and
+// refuses any limit above 100 ("Invalid limit for index tree pagination").
+// A 100k-file dataset is therefore ~100 requests bare and ~2000 expanded
+// against a budget the Hub advertises as 500 calls / 300s, which is why
+// expansion is opt-in per mount rather than the default.
+export const TREE_PAGE_SIZE = 1000;
+export const TREE_PAGE_SIZE_EXPANDED = 100;
+// How many hops of `Link: rel="next"` a tree walk will follow. A repo of
+// 100k files is 100 pages; the ceiling exists so a server that answers a
+// self-referential cursor cannot spin forever.
+export const MAX_TREE_PAGES = 1000;
+// The URL segment each repo type is addressed by under /api/. Both the
+// API and the resolve host spell the plural, and this is also the
+// `{repoType}s` the commit and preupload endpoints interpolate.
+export const API_SEGMENTS = {
+    model: 'models',
+    dataset: 'datasets',
+    space: 'spaces',
+};
+// The segment the *content* host spells, which is not the same table: a
+// model's files hang off the bare repo id (huggingface.co/gpt2/resolve/...)
+// while a dataset's and a space's sit under their own segment. Reusing
+// API_SEGMENTS here 404s every model read.
+export const RESOLVE_SEGMENTS = {
+    model: '',
+    dataset: 'datasets',
+    space: 'spaces',
+};
+// How much of a file the preupload probe sends so the Hub can decide
+// regular-vs-LFS. huggingface_hub sends the same 512 bytes.
+export const PREUPLOAD_SAMPLE_BYTES = 512;
+// Statuses worth another attempt. 429 is the documented rate limit (the
+// Hub advertises 500 API calls / 300s and 3000 resolves / 300s in
+// `ratelimit` headers) and the 5xx family is transient by definition.
+// The Hub answers a create for a repository that already exists with
+// this, which is what --exist-ok turns back into success.
+export const HTTP_CONFLICT = 409;
+export const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+export const MAX_RETRIES = 3;
+// How many files one preupload probe asks about. huggingface_hub chunks
+// at the same 256.
+export const COMMIT_CHUNK = 256;
+// Upstream's own default for `hf download --max-workers`. The bound is
+// what matters: the Hub rate-limits its resolvers at 3000 per 300s, so a
+// repository of many small files must not fan out without one.
+export const MAX_DOWNLOAD_WORKERS = 8;
+// Upstream's separator for the flat per-repository cache directory
+// (constants.REPO_ID_SEPARATOR): "models--julien-c--EsperBERTo-small".
+export const REPO_ID_SEPARATOR = '--';
+// What makes a word a pattern rather than a filename. Used to tell an
+// upstream-style variadic --include line from a real filename operand.
+export const GLOB_CHARS = ['*', '?', '['];
+// What a commit says when the caller had nothing to say. The Hub requires
+// a non-empty summary, and a write reaching the backend through `cp` or a
+// redirect has no message of its own to offer.
+export const DEFAULT_COMMIT_MESSAGE = 'Update from mirage';
+//# sourceMappingURL=constants.js.map

package/dist/core/hf_hub/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/core/hf_hub/constants.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAEvE,MAAM,CAAC,MAAM,QAAQ,GAAG,wBAAwB,CAAA;AAEhD,oEAAoE;AACpE,0EAA0E;AAC1E,sEAAsE;AACtE,iCAAiC;AACjC,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAA;AAEtC,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAA;AAE/B,uEAAuE;AACvE,yEAAyE;AACzE,yEAAyE;AACzE,sEAAsE;AACtE,2EAA2E;AAC3E,yEAAyE;AACzE,wEAAwE;AACxE,yDAAyD;AACzD,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA;AAClC,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAA;AAE1C,yEAAyE;AACzE,yEAAyE;AACzE,+CAA+C;AAC/C,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,CAAA;AAElC,uEAAuE;AACvE,kEAAkE;AAClE,gEAAgE;AAChE,MAAM,CAAC,MAAM,YAAY,GAA2B;IAClD,KAAK,EAAE,QAAQ;IACf,OAAO,EAAE,UAAU;IACnB,KAAK,EAAE,QAAQ;CAChB,CAAA;AAED,wEAAwE;AACxE,4EAA4E;AAC5E,uEAAuE;AACvE,2CAA2C;AAC3C,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD,KAAK,EAAE,EAAE;IACT,OAAO,EAAE,UAAU;IACnB,KAAK,EAAE,QAAQ;CAChB,CAAA;AAED,qEAAqE;AACrE,4DAA4D;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,GAAG,CAAA;AAEzC,wEAAwE;AACxE,kEAAkE;AAClE,sEAAsE;AACtE,qEAAqE;AACrE,0DAA0D;AAC1D,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAA;AAEhC,MAAM,CAAC,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;AAChE,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAA;AAE5B,wEAAwE;AACxE,mBAAmB;AACnB,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAA;AAE/B,uEAAuE;AACvE,yEAAyE;AACzE,+DAA+D;AAC/D,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAA;AAErC,mEAAmE;AACnE,uEAAuE;AACvE,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAA;AAErC,sEAAsE;AACtE,uEAAuE;AACvE,MAAM,CAAC,MAAM,UAAU,GAAsB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAA;AAE5D,0EAA0E;AAC1E,0EAA0E;AAC1E,+CAA+C;AAC/C,MAAM,CAAC,MAAM,sBAAsB,GAAG,oBAAoB,CAAA"}

package/dist/core/hf_hub/exists.d.ts

@@ -0,0 +1,6 @@
+import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
+import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
+/** Whether anything exists at a path: a file or a directory. */
+export declare function exists(accessor: HfHubAccessor, path: PathSpec, index?: IndexCacheStore): Promise<boolean>;
+//# sourceMappingURL=exists.d.ts.map

package/dist/core/hf_hub/exists.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exists.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/exists.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAG7D,gEAAgE;AAChE,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,QAAQ,EACd,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAAC,OAAO,CAAC,CAOlB"}

package/dist/core/hf_hub/exists.js

@@ -0,0 +1,25 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { stat } from "./stat.js";
+/** Whether anything exists at a path: a file or a directory. */
+export async function exists(accessor, path, index) {
+    try {
+        await stat(accessor, path, index);
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+//# sourceMappingURL=exists.js.map

package/dist/core/hf_hub/exists.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exists.js","sourceRoot":"","sources":["../../../src/core/hf_hub/exists.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAKvE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,gEAAgE;AAChE,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,QAAuB,EACvB,IAAc,EACd,KAAuB;IAEvB,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/core/hf_hub/lookup.d.ts

@@ -0,0 +1,33 @@
+import { IndexEntry } from '@struktoai/mirage-core/cache/index/config';
+import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
+import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
+/**
+ * What sits at one mount-absolute key.
+ *
+ * `entry` is null for a directory the tree implies but has no row of its own
+ * for, which is why a caller must read `isDir` and `exists` rather than
+ * testing `entry` for truth.
+ */
+export interface Found {
+    entry: IndexEntry | null;
+    children: string[] | null;
+}
+export declare function isDir(found: Found): boolean;
+/**
+ * Resolve one mount-absolute key against the mount's listing.
+ *
+ * The single place the two storage paths are told apart: a workspace mount
+ * answers from its seeded index, and a mount built without one answers from
+ * tables derived from the accessor's tree. Both are built by `indexRows`, so
+ * they cannot disagree.
+ */
+export declare function lookup(accessor: HfHubAccessor, index: IndexCacheStore | undefined, prefix: string, key: string): Promise<Found>;
+/** The mount-absolute key for a mount-local path. */
+export declare function keyOf(prefix: string, local: string): string;
+/** Whether a mount-local path exists as a non-directory. */
+export declare function probeFile(accessor: HfHubAccessor, index: IndexCacheStore | undefined, prefix: string, local: string): Promise<boolean>;
+/** Whether a mount-local path exists as a directory. */
+export declare function probeDir(accessor: HfHubAccessor, index: IndexCacheStore | undefined, prefix: string, local: string): Promise<boolean>;
+/** A row for a directory the tree implies but has no row for. */
+export declare function dirStatEntry(key: string): IndexEntry;
+//# sourceMappingURL=lookup.d.ts.map

package/dist/core/hf_hub/lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/lookup.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAA;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAE/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAG7D;;;;;;GAMG;AACH,MAAM,WAAW,KAAK;IACpB,KAAK,EAAE,UAAU,GAAG,IAAI,CAAA;IACxB,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAA;CAC1B;AAMD,wBAAgB,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAG3C;AAED;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC1B,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC,CAmBhB;AAED,qDAAqD;AACrD,wBAAgB,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED,4DAA4D;AAC5D,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED,wDAAwD;AACxD,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,eAAe,GAAG,SAAS,EAClC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQpD"}

package/dist/core/hf_hub/lookup.js

@@ -0,0 +1,80 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { IndexEntry } from '@struktoai/mirage-core/cache/index/config';
+import { LookupStatus } from '@struktoai/mirage-core/cache/index/config';
+import { ensureLiveIndex, localRows, refillIndex } from "./tree.js";
+function exists(found) {
+    return found.entry !== null || found.children !== null;
+}
+export function isDir(found) {
+    if (found.children !== null)
+        return true;
+    return found.entry !== null && found.entry.resourceType === 'folder';
+}
+/**
+ * Resolve one mount-absolute key against the mount's listing.
+ *
+ * The single place the two storage paths are told apart: a workspace mount
+ * answers from its seeded index, and a mount built without one answers from
+ * tables derived from the accessor's tree. Both are built by `indexRows`, so
+ * they cannot disagree.
+ */
+export async function lookup(accessor, index, prefix, key) {
+    if (index === undefined) {
+        const { entries, children } = await localRows(accessor, prefix);
+        return { entry: entries.get(key) ?? null, children: children.get(key) ?? null };
+    }
+    await ensureLiveIndex(accessor, index, prefix);
+    let result = await index.get(key);
+    let listing = await index.listDir(key);
+    // The index is the whole listing rather than a cache in front of one, so an
+    // *expired* answer means the tree aged out, not that the path is gone.
+    // Refetch once and ask again; a miss against a live index is a real absence
+    // and must not cost a tree fetch.
+    if (result.status === LookupStatus.EXPIRED || listing.status === LookupStatus.EXPIRED) {
+        if (await refillIndex(accessor, index, prefix)) {
+            result = await index.get(key);
+            listing = await index.listDir(key);
+        }
+    }
+    return { entry: result.entry ?? null, children: listing.entries ?? null };
+}
+/** The mount-absolute key for a mount-local path. */
+export function keyOf(prefix, local) {
+    const rel = local.replace(/^\/+|\/+$/g, '');
+    const stem = prefix.replace(/\/+$/, '');
+    if (rel === '')
+        return stem === '' ? '/' : stem;
+    return stem === '' ? `/${rel}` : `${stem}/${rel}`;
+}
+/** Whether a mount-local path exists as a non-directory. */
+export async function probeFile(accessor, index, prefix, local) {
+    const found = await lookup(accessor, index, prefix, keyOf(prefix, local));
+    return exists(found) && !isDir(found);
+}
+/** Whether a mount-local path exists as a directory. */
+export async function probeDir(accessor, index, prefix, local) {
+    return isDir(await lookup(accessor, index, prefix, keyOf(prefix, local)));
+}
+/** A row for a directory the tree implies but has no row for. */
+export function dirStatEntry(key) {
+    const trimmed = key.replace(/\/+$/, '');
+    const cut = trimmed.lastIndexOf('/');
+    return new IndexEntry({
+        id: '',
+        name: (cut === -1 ? trimmed : trimmed.slice(cut + 1)) || '/',
+        resourceType: 'folder',
+    });
+}
+//# sourceMappingURL=lookup.js.map

package/dist/core/hf_hub/lookup.js.map

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

package/dist/core/hf_hub/read.d.ts

@@ -0,0 +1,18 @@
+import type { IndexEntry } from '@struktoai/mirage-core/cache/index/config';
+import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
+import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
+export interface HfHubReadOptions {
+    offset?: number;
+    size?: number;
+}
+/**
+ * The tree row for a path, or the error that says why there is none.
+ *
+ * Shared by every content read so a file, a directory and an absence are told
+ * apart in exactly one place. It also means a read never reaches the network
+ * for a path the listing already knows is absent.
+ */
+export declare function resolveEntry(accessor: HfHubAccessor, pathSpec: PathSpec, index: IndexCacheStore | undefined): Promise<IndexEntry>;
+export declare function read(accessor: HfHubAccessor, path: PathSpec, index?: IndexCacheStore, options?: HfHubReadOptions): Promise<Uint8Array>;
+//# sourceMappingURL=read.d.ts.map

package/dist/core/hf_hub/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/read.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2CAA2C,CAAA;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAE/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAI5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAI7D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,QAAQ,EAClB,KAAK,EAAE,eAAe,GAAG,SAAS,GACjC,OAAO,CAAC,UAAU,CAAC,CASrB;AAED,wBAAsB,IAAI,CACxB,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,QAAQ,EACd,KAAK,CAAC,EAAE,eAAe,EACvB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,UAAU,CAAC,CAoBrB"}

package/dist/core/hf_hub/read.js

@@ -0,0 +1,54 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { record, startOp } from '@struktoai/mirage-core/observe/context';
+import { eisdir, enoent } from '@struktoai/mirage-core/utils/errors';
+import { mountPrefixOf } from '@struktoai/mirage-core/utils/key_prefix';
+import { hubBytes, resolveUrl } from "./client.js";
+import { isDir, keyOf, lookup } from "./lookup.js";
+/**
+ * The tree row for a path, or the error that says why there is none.
+ *
+ * Shared by every content read so a file, a directory and an absence are told
+ * apart in exactly one place. It also means a read never reaches the network
+ * for a path the listing already knows is absent.
+ */
+export async function resolveEntry(accessor, pathSpec, index) {
+    const virtual = pathSpec.virtual;
+    const prefix = mountPrefixOf(pathSpec.virtual, pathSpec.resourcePath);
+    const rel = pathSpec.mountPath.replace(/^\/+|\/+$/g, '');
+    if (rel === '')
+        throw eisdir(virtual);
+    const found = await lookup(accessor, index, prefix, keyOf(prefix, rel));
+    if (isDir(found))
+        throw eisdir(virtual);
+    if (found.entry === null)
+        throw enoent(virtual);
+    return found.entry;
+}
+export async function read(accessor, path, index, options = {}) {
+    await resolveEntry(accessor, path, index);
+    const raw = path.mountPath;
+    const url = resolveUrl(accessor.endpoint, accessor.repoType, accessor.repoId, accessor.revision, accessor.repoPath(raw));
+    // `size: null` is the window's own spelling for "the rest of the file",
+    // which is not the same as asking for no window at all.
+    const hasWindow = (options.offset ?? 0) > 0 || options.size !== undefined;
+    const window = hasWindow
+        ? { offset: options.offset ?? 0, size: options.size ?? null }
+        : undefined;
+    const timer = startOp();
+    const data = await hubBytes(accessor.token, url, window);
+    record('read', raw, accessor.resourceName, data.length, timer);
+    return data;
+}
+//# sourceMappingURL=read.js.map

package/dist/core/hf_hub/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../../src/core/hf_hub/read.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAIvE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAA;AAExE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAA;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAGvE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAOlD;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,QAAuB,EACvB,QAAkB,EAClB,KAAkC;IAElC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAA;IAChC,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;IACrE,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;IACxD,IAAI,GAAG,KAAK,EAAE;QAAE,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;IACrC,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAA;IACvE,IAAI,KAAK,CAAC,KAAK,CAAC;QAAE,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;IACvC,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;QAAE,MAAM,MAAM,CAAC,OAAO,CAAC,CAAA;IAC/C,OAAO,KAAK,CAAC,KAAK,CAAA;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,QAAuB,EACvB,IAAc,EACd,KAAuB,EACvB,UAA4B,EAAE;IAE9B,MAAM,YAAY,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,CAAA;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAA;IAC1B,MAAM,GAAG,GAAG,UAAU,CACpB,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,MAAM,EACf,QAAQ,CAAC,QAAQ,EACjB,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CACvB,CAAA;IACD,wEAAwE;IACxE,wDAAwD;IACxD,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,CAAA;IACzE,MAAM,MAAM,GAA2B,SAAS;QAC9C,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,IAAI,EAAE;QAC7D,CAAC,CAAC,SAAS,CAAA;IACb,MAAM,KAAK,GAAG,OAAO,EAAE,CAAA;IACvB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,MAAM,CAAC,CAAA;IACxD,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;IAC9D,OAAO,IAAI,CAAA;AACb,CAAC"}

package/dist/core/hf_hub/readdir.d.ts

@@ -0,0 +1,10 @@
+import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
+import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
+/**
+ * List one directory of the repository.
+ *
+ * Answers in mount-absolute paths, the way the index keys them.
+ */
+export declare function readdir(accessor: HfHubAccessor, pathSpec: PathSpec, index?: IndexCacheStore): Promise<string[]>;
+//# sourceMappingURL=readdir.d.ts.map

package/dist/core/hf_hub/readdir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readdir.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/readdir.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAA;AAC/E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAG5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAG7D;;;;GAIG;AACH,wBAAsB,OAAO,CAC3B,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,QAAQ,EAClB,KAAK,CAAC,EAAE,eAAe,GACtB,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnB"}

package/dist/core/hf_hub/readdir.js

@@ -0,0 +1,35 @@
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { listingError } from '@struktoai/mirage-core/utils/errors';
+import { mountPrefixOf } from '@struktoai/mirage-core/utils/key_prefix';
+import { keyOf, lookup, probeDir, probeFile } from "./lookup.js";
+/**
+ * List one directory of the repository.
+ *
+ * Answers in mount-absolute paths, the way the index keys them.
+ */
+export async function readdir(accessor, pathSpec, index) {
+    const prefix = mountPrefixOf(pathSpec.virtual, pathSpec.resourcePath);
+    const target = pathSpec.pattern === null ? pathSpec : pathSpec.dir;
+    const path = target.mountPath;
+    const found = await lookup(accessor, index, prefix, keyOf(prefix, path));
+    if (found.children !== null)
+        return found.children;
+    // A git tree implies every directory above a path it holds, so this store
+    // cannot hold an orphan and the one-probe form is the right one; both probes
+    // are map lookups against a listing already in memory, so the walk costs no
+    // requests.
+    throw await listingError(pathSpec, path, (p) => probeFile(accessor, index, prefix, p), (p) => probeDir(accessor, index, prefix, p));
+}
+//# sourceMappingURL=readdir.js.map

package/dist/core/hf_hub/readdir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readdir.js","sourceRoot":"","sources":["../../../src/core/hf_hub/readdir.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,kEAAkE;AAClE,mEAAmE;AACnE,0CAA0C;AAC1C,EAAE;AACF,iDAAiD;AACjD,EAAE;AACF,sEAAsE;AACtE,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,iCAAiC;AACjC,uEAAuE;AAIvE,OAAO,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAA;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,yCAAyC,CAAA;AAEvE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAEhE;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,QAAuB,EACvB,QAAkB,EAClB,KAAuB;IAEvB,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,YAAY,CAAC,CAAA;IACrE,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAA;IAClE,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAA;IAC7B,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAA;IACxE,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC,QAAQ,CAAA;IAClD,0EAA0E;IAC1E,6EAA6E;IAC7E,4EAA4E;IAC5E,YAAY;IACZ,MAAM,MAAM,YAAY,CACtB,QAAQ,EACR,IAAI,EACJ,CAAC,CAAS,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,EACpD,CAAC,CAAS,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CACpD,CAAA;AACH,CAAC"}