@banou/ponyfill 0.0.3 → 0.0.5

package/README.md

@@ -58,10 +58,18 @@ That is not hypothetical. It is why four of ripple's storage eviction tests sat
 they filled the origin to provoke that condition, and 3.5 GB of padding left the free figure
 identical to the byte.
 
-This package does **not** invent a normalised quota, because there is no honest number to invent: on
-Chromium you really can write 10 more GiB, so the native answer is true. It names the two shapes
-(`QUOTA_CEILING`) and can measure which one an origin has (`measureQuotaCeiling`), by writing a
-sparse probe and watching, because at rest the two are indistinguishable.
+**The behaviour picked is Firefox's: a ceiling does not rise because you put something under it.**
+`quota` is reported as the lowest the platform has stated for this origin, which needs no probe and
+no user agent sniffing, and invents nothing: the platform really did say the origin could hold that
+much. Two ordinary things are broken by the rising version, and both were seen in ripple:
+`usage / quota` as a gauge never fills, and `quota - usage < floor` never fires, so nothing can
+detect pressure at all.
+
+The cost is deliberate and in the safe direction. On Chromium, once bytes are written the reported
+headroom is smaller than what could really be written, so a caller reclaims cache slightly early.
+Cache is the thing that can be fetched again; a caller that never reclaims because it never sees
+pressure is the failure this replaces. The ceiling still follows the platform DOWNWARD, and is never
+reported below the bytes already held, so `quota - usage` reaches zero and never goes negative.
 
 ## Adding to it
 

package/build/index.cjs

@@ -1,8 +1,3 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_storage = require("./storage.cjs");
-exports.QUOTA_CEILING = require_storage.QUOTA_CEILING;
-exports.correctedUsage = require_storage.correctedUsage;
-exports.isUsageUnderReported = require_storage.isUsageUnderReported;
-exports.measureDirectoryBytes = require_storage.measureDirectoryBytes;
-exports.measureQuotaCeiling = require_storage.measureQuotaCeiling;
 exports.storage = require_storage.storage;

package/build/index.d.ts

@@ -7,10 +7,15 @@
  *     import { storage } from '@banou/ponyfill'
  *     const { usage, quota } = await storage.estimate()
  *
- * That constraint is the whole design. A polyfill that patched `navigator.storage` would change what
- * every other script on the page sees, including code that was correct against the real behaviour,
- * and it would make the difference invisible at the call site. An import is greppable, and a package
- * boundary is somewhere the measurement that justifies each workaround can live next to the code.
+ * That constraint is the whole design, and it cuts both ways. A polyfill that patched
+ * `navigator.storage` would change what every other script on the page sees, including code that was
+ * correct against the real behaviour. And an export that is not a platform name is not a ponyfill of
+ * anything: it is a utility library wearing the word. So the surface here is exactly the platform's
+ * surface, and a helper only becomes public if the platform has one by that name.
+ *
+ * Everything else lives behind it. The walk that corrects `estimate().usage`, the bounds on that
+ * walk, and the reconciliation between the measured and reported figures are all internal, because
+ * `navigator.storage` has no such members and neither should this.
  *
  * ## What belongs in here
  *
@@ -22,5 +27,5 @@
  * Every module here states what was measured, on what, and when. A workaround with no measurement
  * behind it is a guess that outlives the bug it was written for.
  */
-export { QUOTA_CEILING, correctedUsage, isUsageUnderReported, measureDirectoryBytes, measureQuotaCeiling, storage, } from './storage';
-export type { QuotaCeiling, StorageEstimate } from './storage';
+export { storage } from './storage';
+export type { StorageEstimate } from './storage';

package/build/index.js

@@ -1,2 +1,2 @@
-import { QUOTA_CEILING, correctedUsage, isUsageUnderReported, measureDirectoryBytes, measureQuotaCeiling, storage } from "./storage.js";
-export { QUOTA_CEILING, correctedUsage, isUsageUnderReported, measureDirectoryBytes, measureQuotaCeiling, storage };
+import { storage } from "./storage.js";
+export { storage };

package/build/storage.cjs

@@ -1,58 +1,39 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/storage.ts
 /**
-* What each engine was measured doing, so a caller can reason without re-running the experiment.
+* Never walk forever: a cycle is impossible in the origin private file system, but a pathological
+* tree is not, and neither is a directory with a hundred thousand entries in it.
 *
-* Deliberately NOT keyed by user agent string and never consulted automatically. It is a record of
-* measurements, for a human reading this file or writing a comment, and
-* {@link measureQuotaCeiling} is what answers the question for the origin actually in front of you.
-*/
-var QUOTA_CEILING = {
-	chromium: {
-		ceiling: "elastic",
-		measured: "2026-09-03, Chrome 152.0.7977.64, 2.7 TiB free",
-		note: "quota rose 10.737 GB to 12.353 GB across 1.615 GB written, leaving quota - usage at 10,737,418,240 bytes after every write, unmoved to the byte"
-	},
-	firefox: {
-		ceiling: "fixed",
-		measured: "2026-09-03, Playwright firefox 1532, same machine and origin",
-		note: "quota held at 10,737,418,240 while the headroom fell by the 1,613,063,025 bytes written, byte for byte"
-	}
-};
-var isDirectory = (handle) => typeof handle.values === "function";
-/**
-* Never walk forever: a cycle is impossible in OPFS, but a pathological tree is not worth the tick.
-*
-* These are bounds, not correctness: hitting either returns what was counted so far rather than
-* failing, which keeps the answer a floor in the same direction as everything else here.
+* Bounds rather than correctness. Hitting either returns what was counted so far instead of failing,
+* which keeps the answer a floor in the same direction as everything else here.
 */
 var MAX_DEPTH = 8;
 var MAX_ENTRIES = 2e4;
+var isDirectory = (handle) => typeof handle.values === "function";
 /**
-* Every byte under a directory, measured rather than asked for, or `null` when the walk could not
-* be done at all.
+* Every byte under a directory, or `null` when the walk could not be done at all.
 *
-* The null is a distinct third answer and callers depend on it: "the origin holds nothing" and "the
-* file system was unreachable" lead to opposite decisions, and collapsing them to 0 would have
-* {@link correctedUsage} report an empty origin for one that simply could not be read.
+* The null is a distinct third answer and the correction below depends on it: "the origin holds
+* nothing" and "the file system was unreachable" lead to opposite decisions, and collapsing them to
+* 0 would report an empty origin for one that simply could not be read.
 *
-* Counts a file's REPORTED SIZE, which for OPFS is its extent rather than how much of it has been
-* written. That is the same accounting the quota system uses, which is the point: a one byte write a
-* gigabyte into a file is charged a gigabyte, and a measurement disagreeing with the charge would be
-* no more useful than the figure it replaces.
+* Counts a file's REPORTED SIZE, which for this file system is its extent rather than how much of it
+* has been written. That is the same accounting the quota system uses, which is the point: a one byte
+* write a gigabyte into a file is charged a gigabyte, and a measurement that disagreed with the
+* charge would be no more useful than the figure it replaces.
 *
-* An unreadable ENTRY is skipped rather than fatal. A file the engine currently holds an exclusive
-* sync access handle for cannot be opened by anyone else, and `getFile()` on it throws rather than
+* An unreadable ENTRY is skipped rather than fatal. A file something else currently holds an
+* exclusive sync access handle for cannot be opened, and `getFile()` on it throws rather than
 * waiting, so a walk that gave up on the first of those would return nothing for exactly the origins
 * holding the most. The answer is therefore a floor: short by the files open right now, never long.
 */
-var measureDirectoryBytes = async (directory, { maxDepth = 8, maxEntries = MAX_ENTRIES } = {}) => {
+var walkBytes = async (directory) => {
 	let total = 0;
 	let seen = 0;
 	const visit = async (handle, depth) => {
-		if (depth > maxDepth) return;
+		if (depth > MAX_DEPTH) return;
 		for await (const child of handle.values()) {
-			if (++seen > maxEntries) return;
+			if (++seen > MAX_ENTRIES) return;
 			if (isDirectory(child)) {
 				await visit(child, depth + 1);
 				continue;
@@ -69,61 +50,73 @@ var measureDirectoryBytes = async (directory, { maxDepth = 8, maxEntries = MAX_E
 	}
 };
 /**
-* The usage figure to believe, given what the browser said and what a walk found.
+* The usage to report, given what the platform said and what the walk found.
 *
-* The larger of the two, and the reason is asymmetric: a browser that OVER-reports has never been
-* observed, while one that under-reports by six orders of magnitude has. So the walk can only ever
-* raise the answer.
-*
-* `usageDetails.fileSystem` is subtracted out before the walk is added when the browser volunteers
-* it, because everything else the browser counts (IndexedDB, caches, service worker registrations)
-* it counts correctly and the walk cannot see any of it. Without that split, an origin holding real
-* IndexedDB data would have it silently dropped from the total.
-*
-* Pure, so the arithmetic is testable without a browser: this is the part that can be wrong in a way
-* no integration test would notice.
+* The walk can only ever RAISE the answer: a browser over-reporting has never been observed, while
+* one under-reporting by six orders of magnitude has.
 */
-var correctedUsage = (estimate, walkedBytes) => {
+var reconcile = (estimate, walked) => {
 	const reported = estimate.usage;
-	if (walkedBytes === null || !Number.isFinite(walkedBytes) || walkedBytes < 0) return reported ?? null;
-	if (reported === void 0) return walkedBytes;
+	if (walked === null || !Number.isFinite(walked) || walked < 0) return reported;
+	if (reported === void 0) return walked;
 	const fileSystem = estimate.usageDetails?.fileSystem;
 	if (typeof fileSystem === "number") {
 		const other = Math.max(0, reported - fileSystem);
-		return Math.max(reported, walkedBytes + other);
+		return Math.max(reported, walked + other);
 	}
-	return Math.max(reported, walkedBytes);
+	return Math.max(reported, walked);
 };
-/** True when the browser's own figure is too far below the measured one to be believed. */
-var isUsageUnderReported = (estimate, walkedBytes) => walkedBytes !== null && walkedBytes > 0 && (estimate.usage ?? 0) < walkedBytes / 2;
 /**
-* `navigator.storage`, with the same method names.
+* The narrowest quota this origin has reported, which is the one that gets reported back.
+*
+* THE DIVERGENCE, AND THE PICK. `quota - usage` already means the same on both engines: bytes you
+* can still write. What diverges is `quota` as a TOTAL, and Chromium never states one. It states
+* `usage + headroom`, recomputed on every read, so the number grows as you fill the origin: measured
+* 10.737 GB rising to 12.353 GB across 1.615 GB written. Firefox states a real total and holds it.
+*
+* Two things a caller does with `quota` are broken by the growing version and neither is exotic:
+*
+*  - `usage / quota` as a gauge never fills, because the denominator runs away from the numerator.
+*    Ripple showed "2 MB / 10.74 GB" over a library holding 1.78 GB for exactly this reason.
+*  - `quota - usage < floor` never fires, so nothing can ever detect pressure. That is what left four
+*    of ripple's eviction tests failing for months against a condition that could not occur.
+*
+* So the behaviour picked here is FIREFOX'S: a ceiling, and a ceiling does not rise because you put
+* something under it. It is implemented as the lowest quota seen for this origin, which needs no
+* probe and no user agent sniffing, and it is TRUE in the strong sense: the platform really did say
+* the origin could hold this much, and nothing here invents a number the platform never stated.
+*
+* The cost is deliberate and is in the safe direction. On Chromium, once some bytes are written, the
+* reported headroom is smaller than what could really be written, so a caller reclaims cache
+* slightly early. Cache is the thing that can be fetched again; a caller that never reclaims because
+* it never sees pressure is the failure this replaces.
 *
-* Only `estimate` behaves differently from the platform's, and only in the way documented at the top
-* of this file. The rest are passed straight through so that a caller can import this once and never
-* reach for the global, which is what keeps the difference in one place instead of at every call
-* site that happens to remember.
+* In memory, and per page. Persisting it would mean owning storage to describe storage, and a reload
+* re-anchors on a figure the platform stated at that moment, which is the same guarantee.
 */
+var narrowest;
+var ceiling = (reported, usage) => {
+	if (reported === void 0) return void 0;
+	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
+	return Math.max(narrowest, usage ?? 0);
+};
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
 	*
-	* Falls back to the browser's own figure whenever the walk cannot be done: no origin private file
-	* system, a directory that will not enumerate, or a platform with no `estimate` at all. Falling
-	* back is not a silent downgrade, because the browser's figure is a floor rather than a guess: it
-	* is never observed to be too HIGH.
+	* Falls back to the platform's own figure whenever the walk cannot be done: no origin private file
+	* system, a directory that will not enumerate, or no `estimate` at all. That is not a silent
+	* downgrade, because the platform's figure is a floor rather than a guess.
 	*/
 	estimate: async () => {
 		const native = globalThis.navigator?.storage;
-		if (!native?.estimate) return {
-			usage: 0,
-			quota: 0
-		};
+		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const walked = native.getDirectory ? await native.getDirectory().then((directory) => measureDirectoryBytes(directory)).catch(() => null) : null;
+		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
 		return {
 			...estimate,
-			usage: correctedUsage(estimate, walked) ?? estimate.usage ?? 0
+			usage,
+			quota: ceiling(estimate.quota, usage)
 		};
 	},
 	persist: () => globalThis.navigator?.storage?.persist?.() ?? Promise.resolve(false),
@@ -134,54 +127,5 @@ var storage = {
 		return native.getDirectory();
 	}
 };
-/**
-* Which ceiling this origin has, by WRITING and watching, because nothing else can tell.
-*
-* The two shapes are indistinguishable at rest: at low usage a flat quota and a flat headroom are
-* the same pair of numbers, which is exactly how the difference went unnoticed. Only writing
-* separates them, so this writes, and it is therefore not something to call casually.
-*
-* Sparse, so it costs no real disk: the quota system charges a file's EXTENT, and a single byte
-* written `probeBytes - 1` into a file is charged the whole extent instantly. The probe file is
-* removed again, in a `finally`, whether or not the measurement succeeded.
-*
-* Answers `unknown` rather than guessing when the probe cannot be written or the origin refuses it,
-* because "I could not tell" and "the ceiling is fixed" lead to opposite decisions.
-*/
-var measureQuotaCeiling = async ({ probeBytes = 536870912, name = ".ponyfill-quota-probe" } = {}) => {
-	const native = globalThis.navigator?.storage;
-	if (!native?.estimate || !native.getDirectory) return "unknown";
-	let root;
-	try {
-		root = await native.getDirectory();
-	} catch {
-		return "unknown";
-	}
-	const before = await native.estimate();
-	try {
-		const writable = await (await root.getFileHandle(name, { create: true })).createWritable();
-		await writable.write({
-			type: "write",
-			position: probeBytes - 1,
-			data: /* @__PURE__ */ new Uint8Array(1)
-		});
-		await writable.close();
-		const after = await native.estimate();
-		const written = (after.usage ?? 0) - (before.usage ?? 0);
-		if (written < probeBytes / 2) return "unknown";
-		return (before.quota ?? 0) - (before.usage ?? 0) - ((after.quota ?? 0) - (after.usage ?? 0)) < written / 4 ? "elastic" : "fixed";
-	} catch {
-		return "unknown";
-	} finally {
-		await root.removeEntry(name).catch(() => {});
-	}
-};
 //#endregion
-exports.MAX_DEPTH = MAX_DEPTH;
-exports.MAX_ENTRIES = MAX_ENTRIES;
-exports.QUOTA_CEILING = QUOTA_CEILING;
-exports.correctedUsage = correctedUsage;
-exports.isUsageUnderReported = isUsageUnderReported;
-exports.measureDirectoryBytes = measureDirectoryBytes;
-exports.measureQuotaCeiling = measureQuotaCeiling;
 exports.storage = storage;

package/build/storage.d.ts

@@ -1,180 +1,87 @@
 /**
- * `navigator.storage`, with the two places browsers disagree about it handled in one file.
+ * `navigator.storage`, with the same method names and no extra ones.
  *
- * A PONYFILL, so nothing here touches a global. Import `storage` and call the same method names the
- * platform uses, and the difference is that these answers can be relied on across engines:
+ * A PONYFILL, so nothing here touches a global and nothing here invents API. You import `storage`
+ * and call it exactly as you would the platform's:
  *
  *     import { storage } from '@banou/ponyfill'
  *     const { usage, quota } = await storage.estimate()
  *
- * ## What is actually wrong with the native one
+ * Only `estimate` behaves differently from the platform's, and only by being CORRECT. The rest are
+ * passed straight through so this can be a drop-in for `navigator.storage`, which is the whole point:
+ * a caller that had to mix `storage.estimate()` with `navigator.storage.getDirectory()` would be
+ * back to remembering which half is safe.
  *
- * ### 1. `usage` can be six orders of magnitude short, and nothing says so
+ * ## Why `estimate` cannot be believed as the platform gives it
+ *
+ * ### `usage` can be six orders of magnitude short
  *
  * MEASURED on Chrome 151: an origin holding a VERIFIED 1,783,407,077 bytes of torrent data reported
- * `usage: 1,813,502`, with `usageDetails.fileSystem: 752`. Not a rounding difference, not a stale
- * cache: 752 bytes against 1.78 GB. Anything deciding whether a write will fit from that figure
- * decides that everything fits, and then the write fails with `QuotaExceededError` at whatever
- * moment the real limit is reached.
  *
- * So `estimate()` here WALKS the origin's file system and reports the larger of the two. The walk
- * costs a directory traversal, which is why the native figure is kept as a floor rather than
- * discarded: everything the browser counts that is not the file system is counted correctly, and
- * only the file system part is worth re-measuring.
+ *     usage: 1813502
+ *     usageDetails: { fileSystem: 752, indexedDB: 1809581, serviceWorkerRegistrations: 3169 }
+ *
+ * 752 bytes against 1.78 GB. Not rounding and not lag, and not universal either: another machine
+ * reported the same data correctly, so the figure can neither be trusted nor discarded.
+ *
+ * So `estimate()` WALKS the origin's file system and reports whichever answer is larger. Larger is
+ * the safe direction on purpose. Over-reporting makes a caller reclaim cache slightly early, which
+ * is what cache is for; under-reporting makes it decide there is room forever, and what happens then
+ * is not a full disk, it is a write failing with `QuotaExceededError` at some unrelated moment.
+ *
+ * Where `usageDetails` is available the correction is surgical: the file system component is the
+ * broken one, so it is replaced with the measurement and the components the browser counts correctly
+ * are kept. Without it, the larger of the two is the best available answer.
  *
- * ### 2. `quota` means a different thing on each engine, and the shapes are indistinguishable at rest
+ * ### `quota` means a different thing on each engine
  *
  * MEASURED 2026-09-03, one machine with 2.7 TiB free, one origin, three 512 MiB sparse writes per
  * engine, same page and same code:
  *
- * | engine | quota at rest | quota after 1.615 GB written | `quota - usage` |
+ * | engine | quota at rest | after 1.615 GB written | `quota - usage` |
  * | --- | --- | --- | --- |
- * | Chromium 152 | 10,737,491,968 | 12,353,… , up by exactly what was written | 10,737,418,240 every time, moved 0 bytes |
- * | Firefox | 10,737,418,240 | 10,737,418,240, unmoved | fell 536,870,912 per write |
+ * | Chromium 152 | 10,737,491,968 | rose by exactly what was written | 10,737,418,240 every time, moved 0 bytes |
+ * | Firefox | 10,737,418,240 | unmoved | fell 536,870,912 per write |
  *
  * Both cap at 10 GiB. They cap DIFFERENT QUANTITIES. Chromium's quota is a FLOATING ceiling,
  * `usage + headroom`, so the headroom is a constant and can never shrink however much is written.
  * Firefox's is a FIXED ceiling, so writing consumes it.
  *
- * Neither is a bug. The Storage Standard calls quota "a conservative estimate" and never says how to
+ * Neither is a bug: the Storage Standard calls quota "a conservative estimate" and never says how to
  * compute it. But it means one very common line is dead on one engine and live on the other:
  *
  *     if (quota - usage < someFloor) { ... }   // can never be true on Chromium
  *
- * That is not a hypothetical. It is why four of ripple's eviction tests sat failing for months: they
- * filled the origin to provoke exactly that condition, and on Chromium the target recedes as fast as
- * it is approached, so 3.5 GB of padding left the free figure identical to the byte.
- *
- * This module does NOT paper over that by inventing a normalised quota, because there is no honest
- * number to invent: on Chromium you really can write 10 more GiB, so the native answer is true. What
- * it does is name the two shapes, say which one an origin has, and refuse to let the difference be
- * discovered again by somebody debugging a dead branch. See {@link QUOTA_CEILING} and
- * {@link measureQuotaCeiling}.
+ * Nothing here papers over that, because there is no honest number to substitute: on Chromium you
+ * really can write 10 more GiB, so the platform's answer is true. It is written down here because
+ * the two shapes are indistinguishable at rest, which is how the difference went unnoticed long
+ * enough to leave four of ripple's storage tests failing for months against a condition that could
+ * never occur.
  */
-/** The same shape `navigator.storage.estimate()` resolves to, plus what the browser volunteered. */
-export type StorageEstimate = {
-    usage: number;
-    quota: number;
-    usageDetails?: Record<string, number>;
-};
 /**
- * How an engine's `quota` behaves as bytes are written.
+ * The platform's own `StorageEstimate`, named the same.
  *
- * `fixed` is what most code assumes: a ceiling that stays put, so `quota - usage` falls as you
- * write. `elastic` is Chromium's: the ceiling rises by whatever was written, so `quota - usage` is a
- * constant and never signals pressure. `unknown` is the honest answer before anything has measured
- * it, and it is the default, because the alternative is sniffing the user agent.
+ * Every field optional exactly as the specification has them, so this is a drop-in for what
+ * `navigator.storage.estimate()` resolves to rather than a stricter thing a caller has to adapt to.
  */
-export type QuotaCeiling = 'fixed' | 'elastic' | 'unknown';
-/**
- * What each engine was measured doing, so a caller can reason without re-running the experiment.
- *
- * Deliberately NOT keyed by user agent string and never consulted automatically. It is a record of
- * measurements, for a human reading this file or writing a comment, and
- * {@link measureQuotaCeiling} is what answers the question for the origin actually in front of you.
- */
-export declare const QUOTA_CEILING: Record<string, {
-    ceiling: QuotaCeiling;
-    measured: string;
-    note: string;
-}>;
-/** A directory handle, narrowed to the two members a size walk actually touches. */
-type WalkableDirectory = {
-    values: () => AsyncIterable<WalkableDirectory | WalkableFile>;
-    kind?: string;
-};
-type WalkableFile = {
-    kind?: string;
-    getFile: () => Promise<{
-        size: number;
-    }>;
+export type StorageEstimate = {
+    usage?: number;
+    quota?: number;
+    /** Chrome only, and the whole reason the correction can be surgical rather than merely larger. */
+    usageDetails?: {
+        fileSystem?: number;
+    };
 };
-/**
- * Never walk forever: a cycle is impossible in OPFS, but a pathological tree is not worth the tick.
- *
- * These are bounds, not correctness: hitting either returns what was counted so far rather than
- * failing, which keeps the answer a floor in the same direction as everything else here.
- */
-export declare const MAX_DEPTH = 8;
-export declare const MAX_ENTRIES = 20000;
-/**
- * Every byte under a directory, measured rather than asked for, or `null` when the walk could not
- * be done at all.
- *
- * The null is a distinct third answer and callers depend on it: "the origin holds nothing" and "the
- * file system was unreachable" lead to opposite decisions, and collapsing them to 0 would have
- * {@link correctedUsage} report an empty origin for one that simply could not be read.
- *
- * Counts a file's REPORTED SIZE, which for OPFS is its extent rather than how much of it has been
- * written. That is the same accounting the quota system uses, which is the point: a one byte write a
- * gigabyte into a file is charged a gigabyte, and a measurement disagreeing with the charge would be
- * no more useful than the figure it replaces.
- *
- * An unreadable ENTRY is skipped rather than fatal. A file the engine currently holds an exclusive
- * sync access handle for cannot be opened by anyone else, and `getFile()` on it throws rather than
- * waiting, so a walk that gave up on the first of those would return nothing for exactly the origins
- * holding the most. The answer is therefore a floor: short by the files open right now, never long.
- */
-export declare const measureDirectoryBytes: (directory: WalkableDirectory, { maxDepth, maxEntries }?: {
-    maxDepth?: number;
-    maxEntries?: number;
-}) => Promise<number | null>;
-/**
- * The usage figure to believe, given what the browser said and what a walk found.
- *
- * The larger of the two, and the reason is asymmetric: a browser that OVER-reports has never been
- * observed, while one that under-reports by six orders of magnitude has. So the walk can only ever
- * raise the answer.
- *
- * `usageDetails.fileSystem` is subtracted out before the walk is added when the browser volunteers
- * it, because everything else the browser counts (IndexedDB, caches, service worker registrations)
- * it counts correctly and the walk cannot see any of it. Without that split, an origin holding real
- * IndexedDB data would have it silently dropped from the total.
- *
- * Pure, so the arithmetic is testable without a browser: this is the part that can be wrong in a way
- * no integration test would notice.
- */
-export declare const correctedUsage: (estimate: Partial<StorageEstimate>, walkedBytes: number | null) => number | null;
-/** True when the browser's own figure is too far below the measured one to be believed. */
-export declare const isUsageUnderReported: (estimate: Partial<StorageEstimate>, walkedBytes: number | null) => boolean;
-/**
- * `navigator.storage`, with the same method names.
- *
- * Only `estimate` behaves differently from the platform's, and only in the way documented at the top
- * of this file. The rest are passed straight through so that a caller can import this once and never
- * reach for the global, which is what keeps the difference in one place instead of at every call
- * site that happens to remember.
- */
 export declare const storage: {
     /**
      * Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
      *
-     * Falls back to the browser's own figure whenever the walk cannot be done: no origin private file
-     * system, a directory that will not enumerate, or a platform with no `estimate` at all. Falling
-     * back is not a silent downgrade, because the browser's figure is a floor rather than a guess: it
-     * is never observed to be too HIGH.
+     * Falls back to the platform's own figure whenever the walk cannot be done: no origin private file
+     * system, a directory that will not enumerate, or no `estimate` at all. That is not a silent
+     * downgrade, because the platform's figure is a floor rather than a guess.
      */
     estimate: () => Promise<StorageEstimate>;
     persist: () => Promise<boolean>;
     persisted: () => Promise<boolean>;
     getDirectory: () => Promise<FileSystemDirectoryHandle>;
 };
-/**
- * Which ceiling this origin has, by WRITING and watching, because nothing else can tell.
- *
- * The two shapes are indistinguishable at rest: at low usage a flat quota and a flat headroom are
- * the same pair of numbers, which is exactly how the difference went unnoticed. Only writing
- * separates them, so this writes, and it is therefore not something to call casually.
- *
- * Sparse, so it costs no real disk: the quota system charges a file's EXTENT, and a single byte
- * written `probeBytes - 1` into a file is charged the whole extent instantly. The probe file is
- * removed again, in a `finally`, whether or not the measurement succeeded.
- *
- * Answers `unknown` rather than guessing when the probe cannot be written or the origin refuses it,
- * because "I could not tell" and "the ceiling is fixed" lead to opposite decisions.
- */
-export declare const measureQuotaCeiling: ({ probeBytes, name }?: {
-    probeBytes?: number;
-    name?: string;
-}) => Promise<QuotaCeiling>;
-export {};

package/build/storage.js

@@ -1,57 +1,38 @@
 //#region src/storage.ts
 /**
-* What each engine was measured doing, so a caller can reason without re-running the experiment.
+* Never walk forever: a cycle is impossible in the origin private file system, but a pathological
+* tree is not, and neither is a directory with a hundred thousand entries in it.
 *
-* Deliberately NOT keyed by user agent string and never consulted automatically. It is a record of
-* measurements, for a human reading this file or writing a comment, and
-* {@link measureQuotaCeiling} is what answers the question for the origin actually in front of you.
-*/
-var QUOTA_CEILING = {
-	chromium: {
-		ceiling: "elastic",
-		measured: "2026-09-03, Chrome 152.0.7977.64, 2.7 TiB free",
-		note: "quota rose 10.737 GB to 12.353 GB across 1.615 GB written, leaving quota - usage at 10,737,418,240 bytes after every write, unmoved to the byte"
-	},
-	firefox: {
-		ceiling: "fixed",
-		measured: "2026-09-03, Playwright firefox 1532, same machine and origin",
-		note: "quota held at 10,737,418,240 while the headroom fell by the 1,613,063,025 bytes written, byte for byte"
-	}
-};
-var isDirectory = (handle) => typeof handle.values === "function";
-/**
-* Never walk forever: a cycle is impossible in OPFS, but a pathological tree is not worth the tick.
-*
-* These are bounds, not correctness: hitting either returns what was counted so far rather than
-* failing, which keeps the answer a floor in the same direction as everything else here.
+* Bounds rather than correctness. Hitting either returns what was counted so far instead of failing,
+* which keeps the answer a floor in the same direction as everything else here.
 */
 var MAX_DEPTH = 8;
 var MAX_ENTRIES = 2e4;
+var isDirectory = (handle) => typeof handle.values === "function";
 /**
-* Every byte under a directory, measured rather than asked for, or `null` when the walk could not
-* be done at all.
+* Every byte under a directory, or `null` when the walk could not be done at all.
 *
-* The null is a distinct third answer and callers depend on it: "the origin holds nothing" and "the
-* file system was unreachable" lead to opposite decisions, and collapsing them to 0 would have
-* {@link correctedUsage} report an empty origin for one that simply could not be read.
+* The null is a distinct third answer and the correction below depends on it: "the origin holds
+* nothing" and "the file system was unreachable" lead to opposite decisions, and collapsing them to
+* 0 would report an empty origin for one that simply could not be read.
 *
-* Counts a file's REPORTED SIZE, which for OPFS is its extent rather than how much of it has been
-* written. That is the same accounting the quota system uses, which is the point: a one byte write a
-* gigabyte into a file is charged a gigabyte, and a measurement disagreeing with the charge would be
-* no more useful than the figure it replaces.
+* Counts a file's REPORTED SIZE, which for this file system is its extent rather than how much of it
+* has been written. That is the same accounting the quota system uses, which is the point: a one byte
+* write a gigabyte into a file is charged a gigabyte, and a measurement that disagreed with the
+* charge would be no more useful than the figure it replaces.
 *
-* An unreadable ENTRY is skipped rather than fatal. A file the engine currently holds an exclusive
-* sync access handle for cannot be opened by anyone else, and `getFile()` on it throws rather than
+* An unreadable ENTRY is skipped rather than fatal. A file something else currently holds an
+* exclusive sync access handle for cannot be opened, and `getFile()` on it throws rather than
 * waiting, so a walk that gave up on the first of those would return nothing for exactly the origins
 * holding the most. The answer is therefore a floor: short by the files open right now, never long.
 */
-var measureDirectoryBytes = async (directory, { maxDepth = 8, maxEntries = MAX_ENTRIES } = {}) => {
+var walkBytes = async (directory) => {
 	let total = 0;
 	let seen = 0;
 	const visit = async (handle, depth) => {
-		if (depth > maxDepth) return;
+		if (depth > MAX_DEPTH) return;
 		for await (const child of handle.values()) {
-			if (++seen > maxEntries) return;
+			if (++seen > MAX_ENTRIES) return;
 			if (isDirectory(child)) {
 				await visit(child, depth + 1);
 				continue;
@@ -68,61 +49,73 @@ var measureDirectoryBytes = async (directory, { maxDepth = 8, maxEntries = MAX_E
 	}
 };
 /**
-* The usage figure to believe, given what the browser said and what a walk found.
+* The usage to report, given what the platform said and what the walk found.
 *
-* The larger of the two, and the reason is asymmetric: a browser that OVER-reports has never been
-* observed, while one that under-reports by six orders of magnitude has. So the walk can only ever
-* raise the answer.
-*
-* `usageDetails.fileSystem` is subtracted out before the walk is added when the browser volunteers
-* it, because everything else the browser counts (IndexedDB, caches, service worker registrations)
-* it counts correctly and the walk cannot see any of it. Without that split, an origin holding real
-* IndexedDB data would have it silently dropped from the total.
-*
-* Pure, so the arithmetic is testable without a browser: this is the part that can be wrong in a way
-* no integration test would notice.
+* The walk can only ever RAISE the answer: a browser over-reporting has never been observed, while
+* one under-reporting by six orders of magnitude has.
 */
-var correctedUsage = (estimate, walkedBytes) => {
+var reconcile = (estimate, walked) => {
 	const reported = estimate.usage;
-	if (walkedBytes === null || !Number.isFinite(walkedBytes) || walkedBytes < 0) return reported ?? null;
-	if (reported === void 0) return walkedBytes;
+	if (walked === null || !Number.isFinite(walked) || walked < 0) return reported;
+	if (reported === void 0) return walked;
 	const fileSystem = estimate.usageDetails?.fileSystem;
 	if (typeof fileSystem === "number") {
 		const other = Math.max(0, reported - fileSystem);
-		return Math.max(reported, walkedBytes + other);
+		return Math.max(reported, walked + other);
 	}
-	return Math.max(reported, walkedBytes);
+	return Math.max(reported, walked);
 };
-/** True when the browser's own figure is too far below the measured one to be believed. */
-var isUsageUnderReported = (estimate, walkedBytes) => walkedBytes !== null && walkedBytes > 0 && (estimate.usage ?? 0) < walkedBytes / 2;
 /**
-* `navigator.storage`, with the same method names.
+* The narrowest quota this origin has reported, which is the one that gets reported back.
+*
+* THE DIVERGENCE, AND THE PICK. `quota - usage` already means the same on both engines: bytes you
+* can still write. What diverges is `quota` as a TOTAL, and Chromium never states one. It states
+* `usage + headroom`, recomputed on every read, so the number grows as you fill the origin: measured
+* 10.737 GB rising to 12.353 GB across 1.615 GB written. Firefox states a real total and holds it.
+*
+* Two things a caller does with `quota` are broken by the growing version and neither is exotic:
+*
+*  - `usage / quota` as a gauge never fills, because the denominator runs away from the numerator.
+*    Ripple showed "2 MB / 10.74 GB" over a library holding 1.78 GB for exactly this reason.
+*  - `quota - usage < floor` never fires, so nothing can ever detect pressure. That is what left four
+*    of ripple's eviction tests failing for months against a condition that could not occur.
+*
+* So the behaviour picked here is FIREFOX'S: a ceiling, and a ceiling does not rise because you put
+* something under it. It is implemented as the lowest quota seen for this origin, which needs no
+* probe and no user agent sniffing, and it is TRUE in the strong sense: the platform really did say
+* the origin could hold this much, and nothing here invents a number the platform never stated.
+*
+* The cost is deliberate and is in the safe direction. On Chromium, once some bytes are written, the
+* reported headroom is smaller than what could really be written, so a caller reclaims cache
+* slightly early. Cache is the thing that can be fetched again; a caller that never reclaims because
+* it never sees pressure is the failure this replaces.
 *
-* Only `estimate` behaves differently from the platform's, and only in the way documented at the top
-* of this file. The rest are passed straight through so that a caller can import this once and never
-* reach for the global, which is what keeps the difference in one place instead of at every call
-* site that happens to remember.
+* In memory, and per page. Persisting it would mean owning storage to describe storage, and a reload
+* re-anchors on a figure the platform stated at that moment, which is the same guarantee.
 */
+var narrowest;
+var ceiling = (reported, usage) => {
+	if (reported === void 0) return void 0;
+	narrowest = narrowest === void 0 ? reported : Math.min(narrowest, reported);
+	return Math.max(narrowest, usage ?? 0);
+};
 var storage = {
 	/**
 	* Same name and same shape as the platform's, with `usage` MEASURED rather than reported.
 	*
-	* Falls back to the browser's own figure whenever the walk cannot be done: no origin private file
-	* system, a directory that will not enumerate, or a platform with no `estimate` at all. Falling
-	* back is not a silent downgrade, because the browser's figure is a floor rather than a guess: it
-	* is never observed to be too HIGH.
+	* Falls back to the platform's own figure whenever the walk cannot be done: no origin private file
+	* system, a directory that will not enumerate, or no `estimate` at all. That is not a silent
+	* downgrade, because the platform's figure is a floor rather than a guess.
 	*/
 	estimate: async () => {
 		const native = globalThis.navigator?.storage;
-		if (!native?.estimate) return {
-			usage: 0,
-			quota: 0
-		};
+		if (!native?.estimate) return {};
 		const estimate = await native.estimate();
-		const walked = native.getDirectory ? await native.getDirectory().then((directory) => measureDirectoryBytes(directory)).catch(() => null) : null;
+		const usage = reconcile(estimate, native.getDirectory ? await native.getDirectory().then((directory) => walkBytes(directory)).catch(() => null) : null);
 		return {
 			...estimate,
-			usage: correctedUsage(estimate, walked) ?? estimate.usage ?? 0
+			usage,
+			quota: ceiling(estimate.quota, usage)
 		};
 	},
 	persist: () => globalThis.navigator?.storage?.persist?.() ?? Promise.resolve(false),
@@ -133,47 +126,5 @@ var storage = {
 		return native.getDirectory();
 	}
 };
-/**
-* Which ceiling this origin has, by WRITING and watching, because nothing else can tell.
-*
-* The two shapes are indistinguishable at rest: at low usage a flat quota and a flat headroom are
-* the same pair of numbers, which is exactly how the difference went unnoticed. Only writing
-* separates them, so this writes, and it is therefore not something to call casually.
-*
-* Sparse, so it costs no real disk: the quota system charges a file's EXTENT, and a single byte
-* written `probeBytes - 1` into a file is charged the whole extent instantly. The probe file is
-* removed again, in a `finally`, whether or not the measurement succeeded.
-*
-* Answers `unknown` rather than guessing when the probe cannot be written or the origin refuses it,
-* because "I could not tell" and "the ceiling is fixed" lead to opposite decisions.
-*/
-var measureQuotaCeiling = async ({ probeBytes = 536870912, name = ".ponyfill-quota-probe" } = {}) => {
-	const native = globalThis.navigator?.storage;
-	if (!native?.estimate || !native.getDirectory) return "unknown";
-	let root;
-	try {
-		root = await native.getDirectory();
-	} catch {
-		return "unknown";
-	}
-	const before = await native.estimate();
-	try {
-		const writable = await (await root.getFileHandle(name, { create: true })).createWritable();
-		await writable.write({
-			type: "write",
-			position: probeBytes - 1,
-			data: /* @__PURE__ */ new Uint8Array(1)
-		});
-		await writable.close();
-		const after = await native.estimate();
-		const written = (after.usage ?? 0) - (before.usage ?? 0);
-		if (written < probeBytes / 2) return "unknown";
-		return (before.quota ?? 0) - (before.usage ?? 0) - ((after.quota ?? 0) - (after.usage ?? 0)) < written / 4 ? "elastic" : "fixed";
-	} catch {
-		return "unknown";
-	} finally {
-		await root.removeEntry(name).catch(() => {});
-	}
-};
 //#endregion
-export { MAX_DEPTH, MAX_ENTRIES, QUOTA_CEILING, correctedUsage, isUsageUnderReported, measureDirectoryBytes, measureQuotaCeiling, storage };
+export { storage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/ponyfill",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "main": "build/index.cjs",
   "module": "build/index.js",