@struktoai/mirage-node 0.0.7-alpha.2 → 0.0.7

package/dist/core/hf_hub/constants.js

@@ -11,6 +11,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 // ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+// DEFAULT_IGNORE_PATTERNS and EMPTY_COMMIT_WARNING are huggingface_hub
+// 1.16.4's (Apache-2.0; see licenses/third_party/huggingface_hub.txt).
 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
@@ -73,8 +75,38 @@ 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 = ['*', '?', '['];
+// The file a deletion pattern never removes: the Hub reads its LFS rules from
+// it, so upstream keeps it whatever `--delete` or `repo-files delete` matched.
+export const GITATTRIBUTES = '.gitattributes';
+// What upstream's upload_folder always leaves out of a folder upload
+// (DEFAULT_IGNORE_PATTERNS): a git checkout's own metadata and the hub's local
+// cache folder, wherever they sit in the tree.
+export const DEFAULT_IGNORE_PATTERNS = [
+    '.git',
+    '.git/*',
+    '*/.git',
+    '**/.git/**',
+    '.cache/huggingface',
+    '.cache/huggingface/*',
+    '*/.cache/huggingface',
+    '**/.cache/huggingface/**',
+];
+// What upstream's `create_commit` logs when a commit would change nothing, and
+// then skips it rather than making an empty one.
+export const EMPTY_COMMIT_WARNING = 'No files have been modified since last commit. Skipping to prevent empty commit.\n';
 // 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';
+// The statuses a refused tree walk comes back with when the repository or
+// revision cannot be seen (a first-page 404 EntryNotFound, a key_prefix naming
+// no folder, lists empty before it gets here). A mount reports them as
+// permission denied, which every file tool steps past; `hf download` alone
+// folds them into an empty listing, so its failure path can ask the Hub which
+// absence it was and name it in upstream's words.
+export const ABSENT_STATUSES = new Set([401, 403, 404]);
+// The statuses a download is refused with when the listing was allowed: a
+// gated repo, or a token that expired after the tree loaded. A 404 there is one
+// file gone, not the repo withheld, so it is not among them.
+export const REFUSED_STATUSES = new Set([401, 403]);
 //# sourceMappingURL=constants.js.map

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

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

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

@@ -1,6 +1,8 @@
-import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
-import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { FileStat, 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>;
+/**
+ * Whether anything exists at a path: the mount root, or a path its folder's
+ * listing names. Mirrors Python's `exists`.
+ */
+export declare function exists(_accessor: HfHubAccessor, path: PathSpec, entry?: FileStat | null): Promise<boolean>;
 //# sourceMappingURL=exists.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"exists.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/exists.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAEtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE7D;;;GAGG;AACH,wBAAgB,MAAM,CACpB,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,QAAQ,EACd,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,GACtB,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/core/hf_hub/exists.js

@@ -11,15 +11,12 @@
 // 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;
+import { stripSlash } from '@struktoai/mirage-core/utils/slash';
+/**
+ * Whether anything exists at a path: the mount root, or a path its folder's
+ * listing names. Mirrors Python's `exists`.
+ */
+export function exists(_accessor, path, entry) {
+    return Promise.resolve(stripSlash(path.mountPath) === '' || (entry !== undefined && entry !== null));
 }
 //# sourceMappingURL=exists.js.map

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

@@ -1 +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"}
+{"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;AAGvE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAG/D;;;GAGG;AACH,MAAM,UAAU,MAAM,CACpB,SAAwB,EACxB,IAAc,EACd,KAAuB;IAEvB,OAAO,OAAO,CAAC,OAAO,CACpB,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,CAC7E,CAAA;AACH,CAAC"}

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

@@ -1,33 +1,14 @@
-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';
+import type { PathSpec } from '@struktoai/mirage-core/types';
 /**
- * What sits at one mount-absolute key.
+ * Report a repository the Hub will not show as permission denied.
  *
- * `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.
+ * A 401, 403 or 404 for the repository or revision is the Hub declining to
+ * show the listing, so the path answers the way a directory the caller may not
+ * open does: every file tool already reports that and steps past it, where a
+ * raw Hub error would stop a walk across other mounts. It is never absence,
+ * which reconcile would turn into a delete.
  */
-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;
+export declare function refusalsDenied<T>(pathSpec: PathSpec, run: () => Promise<T>, statuses?: ReadonlySet<number>): Promise<T>;
+/** The error to rethrow for `err`: EACCES for a refusal, `err` itself otherwise. */
+export declare function asRefusal(pathSpec: PathSpec, err: unknown, statuses?: ReadonlySet<number>): unknown;
 //# sourceMappingURL=lookup.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"lookup.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/lookup.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAK5D;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACrB,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAmB,GAC9C,OAAO,CAAC,CAAC,CAAC,CAMZ;AAED,oFAAoF;AACpF,wBAAgB,SAAS,CACvB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,OAAO,EACZ,QAAQ,GAAE,WAAW,CAAC,MAAM,CAAmB,GAC9C,OAAO,CAET"}

package/dist/core/hf_hub/lookup.js

@@ -11,70 +11,28 @@
 // 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';
-}
+import { eacces } from '@struktoai/mirage-core/errors/fs';
+import { HfHubError } from "./client.js";
+import { ABSENT_STATUSES } from "./constants.js";
 /**
- * Resolve one mount-absolute key against the mount's listing.
+ * Report a repository the Hub will not show as permission denied.
  *
- * 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.
+ * A 401, 403 or 404 for the repository or revision is the Hub declining to
+ * show the listing, so the path answers the way a directory the caller may not
+ * open does: every file tool already reports that and steps past it, where a
+ * raw Hub error would stop a walk across other mounts. It is never absence,
+ * which reconcile would turn into a delete.
  */
-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 };
+export async function refusalsDenied(pathSpec, run, statuses = ABSENT_STATUSES) {
+    try {
+        return await run();
     }
-    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);
-        }
+    catch (err) {
+        throw asRefusal(pathSpec, err, statuses);
     }
-    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',
-    });
+/** The error to rethrow for `err`: EACCES for a refusal, `err` itself otherwise. */
+export function asRefusal(pathSpec, err, statuses = ABSENT_STATUSES) {
+    return err instanceof HfHubError && statuses.has(err.status) ? eacces(pathSpec) : err;
 }
 //# sourceMappingURL=lookup.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../src/core/hf_hub/lookup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../src/core/hf_hub/lookup.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;AAGvE,OAAO,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEhD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAAkB,EAClB,GAAqB,EACrB,WAAgC,eAAe;IAE/C,IAAI,CAAC;QACH,OAAO,MAAM,GAAG,EAAE,CAAA;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC1C,CAAC;AACH,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,SAAS,CACvB,QAAkB,EAClB,GAAY,EACZ,WAAgC,eAAe;IAE/C,OAAO,GAAG,YAAY,UAAU,IAAI,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAA;AACvF,CAAC"}

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

@@ -1,18 +1,19 @@
-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 FileStat, 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.
+ * The row's oid, if the response's ETag shows the bytes are that row's.
  *
- * 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.
+ * The listing can be older than the download: the listing lives until the
+ * mount re-lists it, while resolve always serves the revision's current bytes.
+ * Stamping the listing's oid on newer bytes would let a later revert to that
+ * oid pass them off as fresh, so the oid is stamped only when the ETag names
+ * one of the row's own ids (the oid for a plain file, the xet hash for a Xet
+ * one), and otherwise nothing is.
  */
-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>;
+export declare function rowToken(entry: FileStat, etag: string): string | null;
+export declare function read(accessor: HfHubAccessor, path: PathSpec, options?: HfHubReadOptions, entry?: FileStat | null): Promise<Uint8Array>;
 //# sourceMappingURL=read.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/read.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAE3E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAK7D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOrE;AAED,wBAAsB,IAAI,CACxB,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,QAAQ,EACd,OAAO,GAAE,gBAAqB,EAC9B,KAAK,CAAC,EAAE,QAAQ,GAAG,IAAI,GACtB,OAAO,CAAC,UAAU,CAAC,CAyBrB"}

package/dist/core/hf_hub/read.js

@@ -11,35 +11,35 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 // ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
+import { fileEntry } from '@struktoai/mirage-core/core/hierarchy/probe';
 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";
+import {} from '@struktoai/mirage-core/types';
+import { etagValue, hubBytesTagged, resolveUrl } from "./client.js";
+import { REFUSED_STATUSES } from "./constants.js";
+import { refusalsDenied } from "./lookup.js";
 /**
- * The tree row for a path, or the error that says why there is none.
+ * The row's oid, if the response's ETag shows the bytes are that row's.
  *
- * 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.
+ * The listing can be older than the download: the listing lives until the
+ * mount re-lists it, while resolve always serves the revision's current bytes.
+ * Stamping the listing's oid on newer bytes would let a later revert to that
+ * oid pass them off as fresh, so the oid is stamped only when the ETag names
+ * one of the row's own ids (the oid for a plain file, the xet hash for a Xet
+ * one), and otherwise nothing is.
  */
-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 function rowToken(entry, etag) {
+    const ids = new Set();
+    for (const id of [entry.fingerprint, entry.extra.lfs_oid, entry.extra.xet_hash]) {
+        if (typeof id === 'string' && id !== '')
+            ids.add(id);
+    }
+    if (!ids.has(etagValue(etag)))
+        return null;
+    return entry.fingerprint;
 }
-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));
+export async function read(accessor, path, options = {}, entry) {
+    const row = fileEntry(path, entry);
+    const url = resolveUrl(accessor.endpoint, accessor.repoType, accessor.repoId, accessor.revision, accessor.repoPath(path.mountPath));
     // `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;
@@ -47,8 +47,10 @@ export async function read(accessor, path, index, options = {}) {
         ? { 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);
+    const [data, etag] = await refusalsDenied(path, () => hubBytesTagged(accessor.account, url, window), REFUSED_STATUSES);
+    record('read', path.virtual, accessor.vfsName, data.length, timer, {
+        fingerprint: rowToken(row, etag),
+    });
     return data;
 }
 //# sourceMappingURL=read.js.map

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

@@ -1 +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"}
+{"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;AAEvE,OAAO,EAAE,SAAS,EAAE,MAAM,6CAA6C,CAAA;AACvE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAA;AACxE,OAAO,EAAgC,MAAM,8BAA8B,CAAA;AAG3E,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAO5C;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAe,EAAE,IAAY;IACpD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAA;IAC7B,KAAK,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChF,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,KAAK,EAAE;YAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IACtD,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAC1C,OAAO,KAAK,CAAC,WAAW,CAAA;AAC1B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,QAAuB,EACvB,IAAc,EACd,UAA4B,EAAE,EAC9B,KAAuB;IAEvB,MAAM,GAAG,GAAG,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;IAClC,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,IAAI,CAAC,SAAS,CAAC,CAClC,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,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,MAAM,cAAc,CACvC,IAAI,EACJ,GAAG,EAAE,CAAC,cAAc,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,EACnD,gBAAgB,CACjB,CAAA;IACD,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE;QACjE,WAAW,EAAE,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC;KACjC,CAAC,CAAA;IACF,OAAO,IAAI,CAAA;AACb,CAAC"}

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

@@ -1,10 +1,13 @@
-import type { IndexCacheStore } from '@struktoai/mirage-core/cache/index/store';
-import type { PathSpec } from '@struktoai/mirage-core/types';
+import type { DirListing, PathSpec } from '@struktoai/mirage-core/types';
 import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
 /**
- * List one directory of the repository.
+ * A folder's listing, with every folder below it as seeds.
  *
- * Answers in mount-absolute paths, the way the index keys them.
+ * One paged walk answers the whole repository, at the commit the revision's
+ * head names: the head first, and the tree walked at that commit, so the
+ * version the listing carries is the one its rows are at, never a later one a
+ * commit landing between the two requests would give. A Hub that names no
+ * head walks the branch and versions nothing. Mirrors Python's `readdir`.
  */
-export declare function readdir(accessor: HfHubAccessor, pathSpec: PathSpec, index?: IndexCacheStore): Promise<string[]>;
+export declare function readdir(accessor: HfHubAccessor, pathSpec: PathSpec): Promise<DirListing>;
 //# sourceMappingURL=readdir.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"readdir.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/readdir.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAExE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAK7D;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAAC,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAO9F"}

package/dist/core/hf_hub/readdir.js

@@ -11,25 +11,25 @@
 // 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";
+import { stripSlash } from '@struktoai/mirage-core/utils/slash';
+import { refusalsDenied } from "./lookup.js";
+import { headCommit, mountVersion } from "./repo.js";
+import { fetchTree, treeListing } from "./tree.js";
 /**
- * List one directory of the repository.
+ * A folder's listing, with every folder below it as seeds.
  *
- * Answers in mount-absolute paths, the way the index keys them.
+ * One paged walk answers the whole repository, at the commit the revision's
+ * head names: the head first, and the tree walked at that commit, so the
+ * version the listing carries is the one its rows are at, never a later one a
+ * commit landing between the two requests would give. A Hub that names no
+ * head walks the branch and versions nothing. Mirrors Python's `readdir`.
  */
-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));
+export async function readdir(accessor, pathSpec) {
+    const rel = stripSlash((pathSpec.pattern === null ? pathSpec : pathSpec.dir).mountPath);
+    const [head, tree] = await refusalsDenied(pathSpec, async () => {
+        const found = (await headCommit(accessor)) || null;
+        return [found, await fetchTree(accessor, found ?? undefined)];
+    });
+    return treeListing(tree, rel, mountVersion(head, accessor.keyPrefix), pathSpec.virtual);
 }
 //# sourceMappingURL=readdir.js.map

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

@@ -1 +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"}
+{"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;AAGvE,OAAO,EAAE,UAAU,EAAE,MAAM,oCAAoC,CAAA;AAE/D,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AACpD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAElD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,QAAuB,EAAE,QAAkB;IACvE,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,QAAQ,CAAC,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,CAAA;IACvF,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,MAAM,cAAc,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAC7D,MAAM,KAAK,GAAG,CAAC,MAAM,UAAU,CAAC,QAAQ,CAAC,CAAC,IAAI,IAAI,CAAA;QAClD,OAAO,CAAC,KAAK,EAAE,MAAM,SAAS,CAAC,QAAQ,EAAE,KAAK,IAAI,SAAS,CAAC,CAAU,CAAA;IACxE,CAAC,CAAC,CAAA;IACF,OAAO,WAAW,CAAC,IAAI,EAAE,GAAG,EAAE,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;AACzF,CAAC"}

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

@@ -1,6 +1,16 @@
 import type { HfHubAccessor } from '../../accessor/hf_hub.ts';
-/** The repository's branches, tags and conversion refs. */
-export declare function fetchRefs(accessor: HfHubAccessor): Promise<Record<string, unknown>>;
+/**
+ * The version a mount's listings are stored and checked at.
+ *
+ * The head commit, joined with the key prefix when the mount has one: the
+ * index keys are mount-relative, so two mounts of one repository at one head
+ * but different key prefixes hold different listings under the same keys, and
+ * must not match each other's version. ':' cannot occur in a hex sha, and a
+ * mount with no key prefix keeps the plain head.
+ *
+ * Mirrors Python's `mount_version`.
+ */
+export declare function mountVersion(head: string | null, keyPrefix: string): string | null;
 /**
  * The commit the mount's revision currently points at.
  *
@@ -26,11 +36,10 @@ export declare function revisionUrl(accessor: HfHubAccessor): string;
 /**
  * Why a listing came back empty, asked of the Hub directly.
  *
- * `fetchTree` folds 401/403/404 into an empty listing on purpose: a mount's
- * readdir over a repository it cannot see has to render an empty directory
- * rather than raise. A CLI verb wants the opposite, so it asks this on the
- * failure path only, which costs one request and only when something already
- * went wrong.
+ * `hf download` folds a tree walk the Hub refused (401/403/404) into an empty
+ * listing itself, so its failure path can name the absence upstream would. It
+ * asks this on that path only, which costs one request and only when something
+ * already went wrong.
  *
  * The status cannot answer it. A missing repository, a missing revision and a
  * missing file are all 404, and only the Hub's `X-Error-Code` header tells

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

@@ -1 +1 @@
-{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/repo.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAG7D,2DAA2D;AAC3D,wBAAsB,SAAS,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAIzF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAKzE;AAED,mEAAmE;AACnE,oBAAY,OAAO;IACjB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;CACtB;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAO3D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAW/E"}
+{"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../../src/core/hf_hub/repo.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAG7D;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGlF;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CASzE;AAED,mEAAmE;AACnE,oBAAY,OAAO;IACjB,OAAO,YAAY;IACnB,IAAI,SAAS;IACb,QAAQ,aAAa;CACtB;AAED,uEAAuE;AACvE,wBAAgB,WAAW,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAO3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAW/E"}

package/dist/core/hf_hub/repo.js

@@ -12,11 +12,21 @@
 // limitations under the License.
 // ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========
 import { apiUrl, HfHubError, hubGet, revSegment } from "./client.js";
-/** The repository's branches, tags and conversion refs. */
-export async function fetchRefs(accessor) {
-    const url = apiUrl(accessor.endpoint, accessor.repoType, accessor.repoId, '/refs');
-    const data = await hubGet(accessor.token, url);
-    return typeof data === 'object' && data !== null ? data : {};
+/**
+ * The version a mount's listings are stored and checked at.
+ *
+ * The head commit, joined with the key prefix when the mount has one: the
+ * index keys are mount-relative, so two mounts of one repository at one head
+ * but different key prefixes hold different listings under the same keys, and
+ * must not match each other's version. ':' cannot occur in a hex sha, and a
+ * mount with no key prefix keeps the plain head.
+ *
+ * Mirrors Python's `mount_version`.
+ */
+export function mountVersion(head, keyPrefix) {
+    if (head === null || head === '')
+        return null;
+    return keyPrefix === '' ? head : `${head}:${keyPrefix}`;
 }
 /**
  * The commit the mount's revision currently points at.
@@ -32,7 +42,11 @@ export async function fetchRefs(accessor) {
  * finds the snapshot already there and serves dev's bytes.
  */
 export async function headCommit(accessor) {
-    const data = await hubGet(accessor.token, revisionUrl(accessor));
+    // Only the sha is read, so only the sha is asked for: the bare object lists
+    // every file (1.5 MB on a large dataset), the trimmed one is about 110
+    // bytes. A param, never part of revisionUrl, which every not-found message
+    // names verbatim.
+    const data = await hubGet(accessor.account, revisionUrl(accessor), { 'expand[]': 'sha' });
     if (data === null || typeof data !== 'object' || Array.isArray(data))
         return '';
     const sha = data.sha;
@@ -52,11 +66,10 @@ export function revisionUrl(accessor) {
 /**
  * Why a listing came back empty, asked of the Hub directly.
  *
- * `fetchTree` folds 401/403/404 into an empty listing on purpose: a mount's
- * readdir over a repository it cannot see has to render an empty directory
- * rather than raise. A CLI verb wants the opposite, so it asks this on the
- * failure path only, which costs one request and only when something already
- * went wrong.
+ * `hf download` folds a tree walk the Hub refused (401/403/404) into an empty
+ * listing itself, so its failure path can name the absence upstream would. It
+ * asks this on that path only, which costs one request and only when something
+ * already went wrong.
  *
  * The status cannot answer it. A missing repository, a missing revision and a
  * missing file are all 404, and only the Hub's `X-Error-Code` header tells
@@ -64,7 +77,7 @@ export function revisionUrl(accessor) {
  */
 export async function classifyAbsence(accessor) {
     try {
-        await hubGet(accessor.token, revisionUrl(accessor));
+        await hubGet(accessor.account, revisionUrl(accessor));
     }
     catch (err) {
         if (err instanceof HfHubError) {