pyric/storage compatibility matrix
82.9% of the public API supported
29 of 35 public API
Status legend
getStorage(app, bucketUrl?) / getStorageSandbox(target, options?) — initializer
getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)getStorageSandbox(ctx) returns a tagged sandbox-target handle (frozen identity)
/ getStorageSandbox(target, options?)getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)getStorageSandbox(sandbox) wraps a bare Sandbox with an anonymous context (auth: null)
/ getStorageSandbox(target, options?)getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)getStorage(app) returns the sandbox handle selected by package resolution
/ getStorageSandbox(target, options?)entry-path:storage runs the canonical initializeApp → getStorage(app) → ref → uploadBytes flow (Structured evidence: storage.ts)getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)Two getStorageSandbox(ctx) calls on the same context return the SAME wrapper (identity-stable)
/ getStorageSandbox(target, options?)unit:service.test.ts ("returns the same handle for repeated calls on the same context")getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)Two getStorageSandbox(sandbox) calls on a bare Sandbox return the SAME wrapper (identity-stable)
/ getStorageSandbox(target, options?)withAuth(null) mints a fresh context per call, so the per-context cache missed and bare-Sandbox calls returned different handles. A Sandbox-keyed cache makes the convenience path stable, matching the docstring. Probe: unit:service.test.ts ("ST-B3: returns the same handle for repeated bare-Sandbox calls").getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)Two different SandboxContexts on the same Sandbox get DIFFERENT handles but share the underlying StorageService (IDB)
/ getStorageSandbox(target, options?)unit:service.test.ts ("shares the underlying StorageService across contexts on the same sandbox")getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)options.bucket round-trips on metadata records; v1 has a single implicit bucket but the field is preserved
/ getStorageSandbox(target, options?)unit:service.test.ts ("records the bucket value on the handle")getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)options.dbName honored on the FIRST call per Sandbox; second-call overrides ignored
/ getStorageSandbox(target, options?)unit:service.test.ts ("dbName only takes effect on the sandbox's first getStorage call")getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)options.rules parsed eagerly — malformed rules throw SyntaxError at config time
/ getStorageSandbox(target, options?)unit:storage/sandbox/rules.test.ts (parse errors propagate from parseStorageRules)getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)The TARGET_SYMBOL brand keeps each handle bound to its owning sandbox service and identity
/ getStorageSandbox(target, options?)unit:service.test.ts (distinct contexts share one service while retaining distinct handles)getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)Unrecognized handle (not produced by a factory) → TypeError "not a FirebaseStorage handle"
/ getStorageSandbox(target, options?)unit:service.test.ts ("rejects an object that was not produced by a factory")getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)getStorage(app, bucketUrl?) opens the bucket the URL names, with its own objects and the rules deployed to it; the app's default bucket is stored under the key pyric-default
/ getStorageSandbox(target, options?)unit:service.test.ts pins a bucket URL other than the app's storageBucket opening its own bucket, and the default bucket's store key pyric-default; unit:storage/per-bucket-rules.test.ts pins each bucket's objects and rules apart. test/apps/storage-per-bucket-rules uploads to the default bucket, gs://media-bucket and an undeployed bucket from the page on the Node host, the SharedWorker and the in-page sandbox, and from server scripts attached to the Node host and under PYRIC_SANDBOX=local, and each enforces the file firebase.json deploys to it (#1313). The in-page plane still reports the default bucket as pyric-default in metadata and references (#1519). (Structured evidence: storage-rules-install.test.ts, scenario.ts)getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)Pyric documents that carry Storage bytes inline as base64 in one JSON string (the in-process storage.json, a --persist state file, a fixture export, an inline state capture, and branch files) refuse a total past MAX_INLINE_STORAGE_BYTES with storage/quota-exceeded, naming the limit, the total, and the by-reference alternative, before any byte is encoded or written
/ getStorageSandbox(target, options?)unit:sandbox/internal/inline-storage-limit.test.ts pins the limit, base64 length counting with and without the Node Buffer global, the refusal of inline captures, and branch saves that write nothing. packages/cli/test/serve/inline-storage-limit.test.ts pins the in-process storage file, the --persist state file, a fixture export, and a fork through the sandbox tool. This is Pyric behavior with no production equivalent: production Storage keeps no such documents.getStorage(app, bucketUrl?) / getStorageSandbox(target, options?)The served firebase/storage entry accepts bare getStorage() and returns the page's shared sandbox handle
/ getStorageSandbox(target, options?)storage.ts, bundler.test.ts)ref(storage[, path]) / ref(parent, path) — reference constructor
ref(storage[, path]) / ref(parent, path)ref(storage) returns the root ref — fullPath === '', name === '', parent === null, root === self
/ ref(parent, path)unit:reference.test.ts ("root reference has empty fullPath, null parent, and equal root")ref(storage[, path]) / ref(parent, path)ref(storage, 'sessions/s1.json') populates fullPath, name (last segment), parent (path without last segment)
/ ref(parent, path)unit:reference.test.ts ("ref(storage, path) populates fullPath and name from the last segment")ref(storage[, path]) / ref(parent, path)Path normalization: leading slashes stripped (/sessions/s1 → sessions/s1)
/ ref(parent, path)unit:reference.test.ts ("normalizes leading/trailing/double slashes")ref(storage[, path]) / ref(parent, path)Path normalization: trailing slashes stripped
/ ref(parent, path)ref(storage[, path]) / ref(parent, path)Path normalization: repeated internal slashes collapsed (a//b → a/b)
/ ref(parent, path)ref(storage[, path]) / ref(parent, path)ref(parent, child) joins relative to parent's fullPath
/ ref(parent, path)unit:reference.test.ts ("ref(parent, child) joins relative to the parent")ref(storage[, path]) / ref(parent, path)parent chain walks back to root (each .parent strips one segment until empty, then null)
/ ref(parent, path)unit:reference.test.ts ("parent traversal walks back to root")ref(storage[, path]) / ref(parent, path)root accessor returns the bucket-root ref regardless of starting depth
/ ref(parent, path)ref(storage[, path]) / ref(parent, path)toString() returns gs://<bucket>/<fullPath>
/ ref(parent, path)unit:reference.test.ts ("toString returns gs://bucket/path")ref(storage[, path]) / ref(parent, path)Reference identity: two ref(s, 'a/b') calls are equal-by-toString but NOT === (value objects, not interned)
/ ref(parent, path)unit:reference.test.ts parent-chain test — each .parent returns a fresh object)ref(storage[, path]) / ref(parent, path)References are mirror-owned value objects; parent and root preserve the same storage handle and path semantics
/ ref(parent, path)unit:reference.test.ts pins parent traversal, root identity, bucket, and path behavior through the public reference interface.ref(storage, 'gs://<bucket>/<path>')A gs://<bucket>/<path> URL gives the same reference as ref(storage, '<path>'), its path not percent-decoded; gs://<bucket> gives the root reference, and gs:// throws storage/invalid-url
client-storage-ref-urls (firebase 12.19.0) records gsDefaultBucket and plainPath (same fullPath and name), gsPathNotDecoded (media/take%20one.wav), gsBucketRoot (fullPath: ''), and gsNoBucket (storage/invalid-url). The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(); both match every case, and a gs:// URL on the default bucket gives the same bucket as the path alone. (Structured evidence: oracle-conformance.test.ts)ref(storage, downloadUrl)A download URL, https://firebasestorage.googleapis.com/v0/b/<bucket>/o/<path> or https://storage.googleapis.com/<bucket>/<path>, gives the reference at the percent-decoded path; the query, such as alt and token, is ignored, and a URL with no object path throws storage/invalid-url
client-storage-ref-urls (firebase 12.19.0) records firebaseDownloadUrl (media/take.wav), firebaseDownloadUrlEncoded (my media/take 1.wav), cloudStorageUrl (media/take.wav), and firebaseUrlNoObject (storage/invalid-url). The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(); both match every case. (Structured evidence: oracle-conformance.test.ts)ref(storage, url)A URL on a host other than Firebase Storage's or Cloud Storage's throws storage/invalid-url
client-storage-ref-urls (firebase 12.19.0) records otherHostUrl (storage/invalid-url). The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(); both throw storage/invalid-url. (Structured evidence: oracle-conformance.test.ts)ref(storage, '<origin>/__pyric/storage/v0/b/<bucket>/o/<path>')Production throws storage/invalid-url for a URL on the Node host's /__pyric/storage/v0/ route, as for any host it does not serve from. The sandbox reads the percent-decoded object path from <origin>/__pyric/storage/v0/b/<bucket>/o/<path> on any origin, as production does from its own download URL
client-storage-ref-urls (firebase 12.19.0) records pyricHostUrl (storage/invalid-url). The Node host's getDownloadURL issues this form, so an app that keeps a download URL and later calls deleteObject(ref(storage, url)) needs ref() to read it. The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(): both pin production's code beside the sandbox's reference, whose fullPath and name equal those production gives for firebaseDownloadUrl. The web byte route fixture in hosted-sqlite.test.ts keeps a download URL from the Node host and deletes the object by ref(storage, url), and hosted smoke test 9 does the same from a Chromium page against the built CLI's Node host. Production never issues this URL, so no production app depends on the error. (Structured evidence: oracle-conformance.test.ts)ref(storage, url).bucketProduction gives a reference on the URL's bucket, including a bucket other than the app's default. The sandbox's ref() keeps the handle's bucket, at the URL's path; getStorage(app, bucketUrl) reaches another bucket
client-storage-ref-urls (firebase 12.19.0) records gsOtherBucket and firebaseDownloadUrlOtherBucket (bucket: 'other-bucket') and gsDefaultBucket (bucket: 'b', the configured bucket). ref() keeps the handle's bucket: a URL naming another bucket reads that path in the handle's bucket. To reach another bucket, an app opens it with getStorage(app, bucketUrl) (storage#11). The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(): both pin production's other-bucket beside the sandbox's bucket and the URL's fullPath. (Structured evidence: oracle-conformance.test.ts)ref(storage, 'data:...')Production reads a string without ://, such as a data: URI, as an object path. The sandbox throws storage/invalid-url for a data: URI
client-storage-ref-urls (firebase 12.19.0) records dataUri (fullPath: 'data:audio/wav;base64,UklGRg==', name: 'wav;base64,UklGRg=='). In process and on a SharedWorker host, getDownloadURL returns a data: URI (storage#51), and no object exists at that literal path, so reading it as a path would make deleteObject(ref(storage, url)) resolve and delete nothing. The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(): both pin production's path beside the sandbox's storage/invalid-url, and the storage oracle suite shows a reference to a data: download URL throws while the object stays.ref(reference, url)Only a Storage instance takes a URL: ref(reference, url) throws storage/invalid-argument
client-storage-ref-urls (firebase 12.19.0) records childRefWithUrl (storage/invalid-argument). The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(); both throw storage/invalid-argument. (Structured evidence: oracle-conformance.test.ts)uploadBytes(ref, data, metadata?) — write blob
uploadBytes(ref, data, metadata?)Accepts Blob payload; returns UploadResult with populated metadata
unit:reference.test.ts ("accepts a Blob and round-trips through getBlob")uploadBytes(ref, data, metadata?)Accepts Uint8Array payload
unit:reference.test.ts ("accepts a Uint8Array")uploadBytes(ref, data, metadata?)Accepts ArrayBuffer payload
unit:reference.test.ts ("accepts an ArrayBuffer")uploadBytes(ref, data, metadata?)ContentType precedence: caller's metadata.contentType > Blob.type > application/octet-stream
unit:reference.test.ts ("metadata.contentType overrides the Blob's intrinsic type" + "falls back to application/octet-stream when no type is supplied")uploadBytes(ref, data, metadata?)Blob.type === '' (no intrinsic type) falls through to application/octet-stream, NOT to ''
unit:reference.test.ts ("falls back to application/octet-stream when no type is supplied")uploadBytes(ref, data, metadata?)customMetadata round-trips through the upload pipeline
unit:reference.test.ts ("round-trips customMetadata") + unit:metadata.test.tsuploadBytes(ref, data, metadata?)Empty Blob.type rewrap: when caller hint differs from Blob.type, the blob is re-wrapped with the caller's type (same bytes)
unit:reference.test.ts ("metadata.contentType overrides the Blob's intrinsic type")uploadBytes(ref, data, metadata?)Throws storage/invalid-root-operation when called on the root reference
unit:reference.test.ts ("throws on root reference")uploadBytes(ref, data, metadata?)Returned metadata.fullPath matches the ref's fullPath
uploadBytes(ref, data, metadata?)Returned metadata.size matches the input blob's byte length
uploadBytes(ref, data, metadata?)Returned metadata.bucket matches the storage handle's bucket
uploadBytes(ref, data, metadata?)Replaces any existing object at the path (overwrite, not append)
unit:upstream-storage-probes.test.ts ("second uploadBytes at the same path replaces bytes and metadata")uploadBytes(ref, data, metadata?)Prod: round-trips uploaded bytes through getDownloadURL + fetch (byte-for-byte equality)
packages/conformance/observations/storage/storage-upload-bytes-roundtrip.json (against digame-mas, fb-js-sdk 12.19.0: 6-byte payload → uploadBytes → getDownloadURL → HTTPS fetch → bytesMatch: true, urlIsHttps: true, bodyLen === payloadLen === 6). This row records the production answer key; row #51 compares the sandbox's URL forms, hosted and in-process, against it.uploadBytes(ref, data, metadata?)Returned metadata.contentType matches what the caller hinted (when set)
unit:reference.test.ts + oracle: packages/conformance/observations/storage/storage-upload-then-getmetadata.json (contentType: 'application/octet-stream' round-trip against digame-mas, fb-js-sdk 12.19.0; contentTypeMatches: true)uploadBytes(ref, data, metadata?)Returned metadata.generation / metageneration are stringified counters ('1' after fresh upload)
uploadBytes(ref, data, metadata?)Each write of an object gets a new, larger generation, a numeric string, even in one millisecond, under a fixed clock, or from two sandboxes on one store
generation.test.ts, generation-high-water.test.ts, worker, Node host and pyric-admin generation tests. Shape: oracle storage-upload-then-getmetadata.json (Structured evidence: storage-generation.test.ts, hosted-sqlite.test.ts, generations.test.ts)uploadString(ref, value, format?, metadata?) — write string-form
uploadString(ref, value, format?, metadata?)format='raw' (default): UTF-8 encodes the string; contentType defaults to text/plain;charset=utf-8
unit:reference.test.ts ("raw format encodes UTF-8 and defaults contentType to text/plain")uploadString(ref, value, format?, metadata?)format='base64': decodes payload bytes from standard base64
unit:reference.test.ts ("base64 format decodes payload bytes")uploadString(ref, value, format?, metadata?)Sandbox: format='base64url' (or any unknown format) rejected with storage/invalid-format naming the bad format. Prod: base64url is ACCEPTED (upload succeeds); a genuinely-unrecognized format throws storage/unknown
packages/conformance/observations/storage/storage-uploadstring-unknown-format.json: prod accepts base64url (base64urlOk: true) and throws storage/unknown for an unrecognized format — not storage/invalid-format. The v1 sandbox ships only raw/base64/data_url (matches StringFormat) and throws storage/invalid-format for anything else (ST-B3 replaced the old mis-parse-as-data_url behavior). Both sides pinned in oracle-conformance.test.ts; sandbox code path documented in upload.ts's decodeString. Implementing base64url decoding is still one line in decodeString. (Structured evidence: error-codes.test.ts)uploadString(ref, value, format?, metadata?)format='data_url': parses data:<mime>;base64,<payload>, infers contentType from prefix
unit:reference.test.ts ("data_url format infers contentType from the prefix")uploadString(ref, value, format?, metadata?)format='data_url' with non-base64 payload: percent-decodes the body
unit:upstream-storage-probes.test.ts ("non-base64 data_url percent-decodes the body"; malformed %%0 → storage/invalid-format)uploadString(ref, value, format?, metadata?)Caller's metadata.contentType beats data_url inference
unit:reference.test.ts ("caller metadata.contentType beats data_url inference")uploadString(ref, value, format?, metadata?)Malformed data_url (no comma / doesn't start with data:) throws TypeError with "data_url format" message
unit:reference.test.ts ("throws on malformed data_url")uploadString(ref, value, format?, metadata?)uploadString(ref, value, 'base64') round-trips via getDownloadURL + fetch across in-page sandbox and SharedWorker mode
packages/conformance/observations/storage/storage-uploadstring-base64-roundtrip.json ('aGVsbG8=' → 'hello' against digame-mas, fb-js-sdk 12.19.0; textMatches: true). Sandbox oracle replay matches production behavior in-page, and client↔host integration proves SharedWorker mode decodes and transfers string payloads faithfully over the worker port. (Structured evidence: oracle-conformance.test.ts, integration.test.ts)uploadBytesResumable(ref, data, metadata?) — resumable upload + task observers
uploadBytesResumable(ref, data, metadata?)Exported by firebase/storage; returns an UploadTask with pause() / resume() / cancel()
unit:resumable-upload.test.ts confirms uploadBytesResumable(ref, data) returns an UploadTask supporting pause(), resume(), and cancel() over synthetic microtask steps.uploadBytesResumable(ref, data, metadata?)task.on('state_changed', next, error, complete) fires next with {bytesTransferred, totalBytes, state} snapshots
unit:resumable-upload.test.ts confirms synthetic progress snapshots are emitted during task execution without requiring network transfer.uploadBytesResumable(ref, data, metadata?)task.pause() flips state to 'paused'; task.resume() continues
unit:resumable-upload.test.ts confirms calling task.pause() and task.resume() transitions through 'paused' and 'running' states deterministically.uploadBytesResumable(ref, data, metadata?)task.cancel() rejects the upload with storage/canceled
unit:resumable-upload.test.ts confirms cancellation rejects with storage/canceled. A commit already sent cannot be recalled, so a cancel that races it rolls it back, then rejects and tells observers. Production never stores a canceled upload, so its rules never see the rollback: the commit takes a token bound to the client, the generation it stored, and the object it replaced, and the host, without the rules, puts that object back or deletes the new one in one generation-checked write, keeping any later write (#1157, #1159). storage-upload-rollback.test.ts pins the token's binding, the restore, and a cancel under rules that deny every delete; storage-ops.test.ts pins a commit settling after the cancel and one held while paused. The web byte route fixture in hosted-sqlite.test.ts and test/apps/client-sdk-under-register cancel under node --import @pyric/cli/register and read no object, or the earlier one after an overwrite; on main (8e1ee9cb4) the object stayed (#1137). A failed rollback rejects with its own code. The in-page task does the same (#1161), and storage-cancel-parity.test.ts compares the two. (Structured evidence: resumable-cancel-rollback.test.ts, scenario.ts, scenario.ts)getDownloadURL(ref) — read URL
getDownloadURL(ref)Exported by firebase/storage; returns a token-signed HTTPS URL that fetches the blob
storage-upload-bytes-roundtrip records urlIsHttps: true and a byte-identical fetch. The URL form depends on where the sandbox runs. On the Node host, getDownloadURL returns http://<host>/__pyric/storage/v0/b/<bucket>/o/<path>?alt=media&token=<token>: production's /v0/b/<bucket>/o/<path> path and alt=media query, under the host's own origin. The token is kept in the object's downloadTokens metadata, later calls return the same URL, it does not expire, and removing it from the metadata revokes the URL. A GET on the URL needs no header and serves Range. The hosted replay of the observation calls getDownloadURL and fetch through the web client against the host and its byte route, and matches downloadOk, bodyLen, and bytesMatch. The web byte route fixture pins token persistence and revocation, and hosted smoke test 8 streams and seeks an <audio> element by the URL in Chromium. In process and in a SharedWorker there is no HTTP origin to serve from, so getDownloadURL returns a data:<contentType>;base64,... URI that carries the object's bytes. The oracle replay proves its byte-identical fetch and asserts the data: prefix, and the client↔host integration proves SharedWorker mode returns the same form. The divergence is URL identity. The hosted URL is http on the local host's origin, under /__pyric/storage, where production's is https on Google Cloud Storage's host, so it is fetchable only where that host is reachable. The data: form has no token, no revocation, and no stable short string. Production observation admin-storage-metadata-download-url records the token itself: the Firebase metadata endpoint reports it as downloadTokens, firebase-admin sees it as the firebaseStorageDownloadTokens custom key, removing it makes the URL answer 403, and the URL answers Range with 206. (Structured evidence: hosted-sqlite.test.ts, smoke.pw.ts)getDownloadURL(ref)Throws storage/object-not-found for missing objects
storage-delete-then-get-throws records getDownloadURL throwing storage/object-not-found after deletion. The sandbox oracle replay invokes getDownloadURL itself and matches that code, and the hosted replay matches it through the web client against the Node host, whose getDownloadURL runs over the RPC. The public error-code suite also pins the never-existing-object case. (Structured evidence: error-codes.test.ts, oracle-conformance.test.ts, hosted-sqlite.test.ts)getBytes(ref, maxDownloadSize?) — read as ArrayBuffer
getBytes(ref, maxDownloadSize?)Returns the blob's contents as an ArrayBuffer
unit:reference.test.ts ("accepts a Uint8Array" round-trip via getBytes)getBytes(ref, maxDownloadSize?)Throws storage/object-not-found when no object exists at the path
unit:reference.test.ts ("throws storage/object-not-found for missing paths") + oracle: packages/conformance/observations/storage/storage-delete-then-get-throws.json (against digame-mas, fb-js-sdk 12.19.0: upload → delete → getDownloadURL on the deleted ref throws FirebaseError with code: 'storage/object-not-found')getBytes(ref, maxDownloadSize?)When the object exceeds maxDownloadSize, returns a truncated prefix of that byte length (does not throw)
unit:upstream-storage-probes.test.ts ("getBytes / getBlob return a truncated prefix when the object exceeds the cap"). Matches upstream getBytesInternal / getBlobInternal post-fetch slice (GCS may ignore Range on small files). Prior COMPAT claim that the cap throws was wrong.getBytes(ref, maxDownloadSize?)Just-under-cap reads succeed and return the full byte length
unit:upstream-storage-probes.test.ts ("just-under-cap reads return the full object") + unit:reference.test.ts ("honors maxDownloadSizeBytes when the blob is too large")getBytes(ref, maxDownloadSize?)Throws storage/invalid-root-operation when called on the root reference
unit:reference.test.ts ("throws invalid-root-operation on root reads")getBlob(ref, maxDownloadSize?) — read as Blob
getBlob(ref, maxDownloadSize?)Returns the stored bytes wrapped as a Blob (with .type from metadata)
unit:reference.test.ts ("accepts a Blob and round-trips through getBlob")getBlob(ref, maxDownloadSize?)Throws storage/object-not-found for missing paths
unit:reference.test.ts ("throws storage/object-not-found for missing paths")getBlob(ref, maxDownloadSize?)Honors maxDownloadSize same as getBytes
unit:upstream-storage-probes.test.ts ("getBytes / getBlob return a truncated prefix when the object exceeds the cap"; shared fetchBlob helper in download.ts)getBlob(ref, maxDownloadSize?)Root-ref read throws storage/invalid-root-operation
guardNonRoot in download.tsgetStream(ref, maxDownloadSize?) — Node-specific
getStream(ref, maxDownloadSize?)Exported by firebase/storage (Node entry only); returns a Node Readable
pyric/storage implementation or behavioral probe exists; availability is classified by the owning surface contract.deleteObject(ref) — delete
deleteObject(ref)Removes both the blob AND the metadata atomically (post-delete getBlob throws object-not-found)
unit:reference.test.ts ("removes both blob and metadata")deleteObject(ref)Sandbox: no-op on missing path (does NOT throw)
persistence.ts's delete. Prod's deleteObject on a missing path throws storage/object-not-found. Oracle-locked: packages/conformance/observations/storage/storage-delete-missing-throws.json (code: 'storage/object-not-found', name: 'FirebaseError' against digame-mas, fb-js-sdk 12.19.0). Both sides pinned in oracle-conformance.test.ts; documented in download.ts.deleteObject(ref)Throws storage/invalid-root-operation on the root reference
unit:reference.test.ts ("throws invalid-root-operation on root")deleteObject(ref)Prod: a successful deleteObject followed by getDownloadURL on the same ref throws storage/object-not-found
packages/conformance/observations/storage/storage-delete-then-get-throws.json (against digame-mas, fb-js-sdk 12.19.0: upload + delete succeed, then getDownloadURL throws code: 'storage/object-not-found', message "Firebase Storage: Object '…' does not exist.", isFirebaseError: true)deleteObject(ref)Sandbox: writes-then-delete leaves no metadata (post-delete getMetadata throws object-not-found)
getMetadatalistAll(ref) — list all children under a ref
listAll(ref)Returns ListResult with items (direct child files) + prefixes (sub-folder refs) + nextPageToken: undefined
listAll(ref)Empty bucket → both arrays empty, nextPageToken: undefined
unit:list.test.ts ("returns empty arrays on an empty bucket")listAll(ref)Direct children only — does NOT recurse into grandchildren as items
unit:list.test.ts ("does not recurse into grandchildren as items")listAll(ref)Sub-folders surface as prefixes and are deduplicated (many files under one folder → ONE prefix entry)
unit:list.test.ts ("promotes sub-folders into prefixes (deduplicated)")listAll(ref)items sorted by path (IDB key order, lexicographic)
unit:list.test.ts ("lists direct children of a folder")listAll(ref)prefixes sorted lexicographically by fullPath (for determinism)
listAll(ref)The scanned ref itself is NEVER included in items (even when an object exists at the exact prefix path)
unit:list.test.ts ("does not include the scanned ref itself")listAll(ref)listAll(ref(storage)) (root) scans the entire bucket
unit:list.test.ts ("listAll on the root scans the entire bucket")listAll(ref)Items expose the full StorageReference shape (storage, bucket, name, parent)
unit:list.test.ts ("items expose the StorageReference shape")listAll(ref)Prod: items + prefixes shape matches sandbox after N uploads under a directory
packages/conformance/observations/storage/storage-listall-shape.json (against digame-mas, fb-js-sdk 12.19.0: 3 direct children + 1 grandchild → items has all 3 direct children sorted, prefixes has the single sub-folder, itemCount: 3, prefixCount: 1, threeDirectChildren: true, oneSubPrefix: true)listAll(ref)listAll enforces rules: read permission on the scanned prefix path governs list (Firebase: read covers download AND list), denied prefix → storage/unauthorized
list.ts now calls enforceRules with method: 'read' on the listed prefix (was a silent bypass — a denied tree was still fully enumerable). With no rules configured the check is a no-op. Probe: unit:list-rules.test.ts ("denies an anonymous listAll of a tree the rules protect" / "allows an authed listAll"). Note: a read rule scoped to match /sessions/{id} does NOT grant list on /sessions — the folder needs its own read rule, matching prod; the session-archive demo ruleset adds match /sessions { allow read }.list(ref, options?) — paginated list
list(ref, options?)Exported by firebase/storage; accepts { maxResults, pageToken }, returns a ListResult with nextPageToken set when more pages remain
list implementation or behavioral probe exists; availability is classified by the owning surface contract. ListResult.nextPageToken remains optional for forward-compatible consumer code.getMetadata(ref) / updateMetadata(ref, metadata) — metadata ops
getMetadata(ref) / updateMetadata(ref, metadata)getMetadata(ref) returns the same FullMetadata shape uploadBytes produced
/ updateMetadata(ref, metadata)unit:metadata.test.ts ("returns the FullMetadata uploadBytes wrote")getMetadata(ref) / updateMetadata(ref, metadata)getMetadata(ref) throws storage/object-not-found for missing paths
/ updateMetadata(ref, metadata)unit:metadata.test.ts ("throws object-not-found for missing paths")getMetadata(ref) / updateMetadata(ref, metadata)getMetadata(ref) throws storage/invalid-root-operation on the root
/ updateMetadata(ref, metadata)unit:metadata.test.ts ("throws invalid-root-operation on the root reference")getMetadata(ref) / updateMetadata(ref, metadata)updateMetadata(ref, patch) replaces the listed client-settable fields wholesale (per Firebase semantics)
/ updateMetadata(ref, metadata)unit:metadata.test.ts ("replaces settable fields, bumps metageneration, refreshes updated")getMetadata(ref) / updateMetadata(ref, metadata)updateMetadata bumps metageneration by 1 on each call
/ updateMetadata(ref, metadata)getMetadata(ref) / updateMetadata(ref, metadata)updateMetadata refreshes updated to the call moment; timeCreated and generation stay pinned
/ updateMetadata(ref, metadata)getMetadata(ref) / updateMetadata(ref, metadata)updateMetadata preserves the blob bytes (only metadata changes)
/ updateMetadata(ref, metadata)unit:metadata.test.ts ("leaves the blob content untouched")getMetadata(ref) / updateMetadata(ref, metadata)updateMetadata with undefined field values preserves the prior value (does NOT clear it)
/ updateMetadata(ref, metadata)null to explicitly clear a field. Sandbox doesn't model null-clear (per metadata.ts doc comment). Documented; not probe-locked.getMetadata(ref) / updateMetadata(ref, metadata)updateMetadata throws storage/object-not-found for missing paths
/ updateMetadata(ref, metadata)unit:metadata.test.ts ("throws object-not-found when the path is missing")getMetadata(ref) / updateMetadata(ref, metadata)updateMetadata throws storage/invalid-root-operation on the root
/ updateMetadata(ref, metadata)unit:metadata.test.ts ("throws invalid-root-operation on the root reference")getMetadata(ref) / updateMetadata(ref, metadata)Prod: getMetadata after uploadBytes returns contentType and size matching what was uploaded
/ updateMetadata(ref, metadata)packages/conformance/observations/storage/storage-upload-then-getmetadata.json (against digame-mas, fb-js-sdk 12.19.0: upload 128-byte payload with contentType: 'application/octet-stream', getMetadata returns metadataSize: 128, metadataContentType: 'application/octet-stream', metadataBucket: 'digame-mas.appspot.com', metadataMetageneration: '1', fullPathMatches: true) (Structured evidence: persistence-state.test.ts, hosted-sqlite.test.ts)getMetadata(ref) / updateMetadata(ref, metadata)Prod: updateMetadata({customMetadata: {...}}) round-trips through a follow-up getMetadata
/ updateMetadata(ref, metadata)packages/conformance/observations/storage/storage-update-metadata-roundtrip.json (against digame-mas, fb-js-sdk 12.19.0: post-update getMetadata returns the exact customMetadata object, metageneration bumps '1' → '2', customSurvived: true, metagenerationBumped: true)getMetadata(ref) / updateMetadata(ref, metadata)FullMetadata.md5Hash populated on uploads
/ updateMetadata(ref, metadata)md5Hash. Oracle-locked: packages/conformance/observations/storage/storage-upload-then-getmetadata.json confirms prod sets md5Hash (hasMd5Hash: true after a vanilla uploadBytes). Both sides pinned in oracle-conformance.test.ts. Aligning the sandbox is a one-spot fix in upload.ts's buildStoredMetadata.getMetadata(ref) / updateMetadata(ref, metadata)FullMetadata.ref lazy population (prod populates lazily)
/ updateMetadata(ref, metadata)pyric/storage — metadata.ts explicitly omits ref from FullMetadataconnectStorageEmulator(storage, host, port) — emulator hook
connectStorageEmulator(storage, host, port)Exported by firebase/storage; reroutes a FirebaseStorage handle to a local emulator
pyric/storage — the sandbox IS the local-target alternative; emulator parity is out of scope per index.tsOp-level rules enforcement — a denied op throws storage/unauthorized
These are Storage SDK behaviors: how an upload / read / metadata / delete op
surfaces a rules deny verdict. The rules-engine fidelity rows
(parseStorageRules / evaluateStorageRules vs the production Rules Test
API) moved to the native storage-rules surface (docs/rules/COMPAT.md).
Rules enforcementOp-level enforcement: uploadBytes against a denied path throws storage/unauthorized on sandbox / storage/unauthorized on prod, .code exposed on both
StorageError (see src/storage/errors.ts) whose .code === 'storage/unauthorized' — matching prod's FirebaseError.code. Probe: unit:error-codes.test.ts ("unauthorized when rules deny the operation"). Residual divergence (documented, not a .code gap): the sandbox StorageError.name is 'StorageError' (plain Error subclass, same shape as Firestore's SandboxError) where prod reports name: 'FirebaseError' / isFirebaseError: true, and the message wording differs (sandbox embeds the matched-rule reason chain). Oracle-locked: packages/conformance/observations/storage/storage-rules-denied-error-code.json (against digame-mas, fb-js-sdk 12.19.0: code: 'storage/unauthorized', message "Firebase Storage: User does not have permission to access '<path>'.", name: 'FirebaseError', isFirebaseError: true). Extended 2026-10-27: storage-rules-denied-signed-out-error-code (digame-mas, fb-js-sdk 12.19.0) records that with no signed-in user an upload under allow read, write: if request.auth != null and one outside any grant both throw storage/unauthorized with HTTP 403, never storage/unauthenticated; the sandbox gives the same code, pinned by unit:storage/oracle-conformance.test.ts.Rules enforcementgetMetadata against a denied path throws storage/unauthorized
unit:storage/enforce.test.ts (operation-integration section)Rules enforcementupdateMetadata against a denied path throws storage/unauthorized
Rules enforcementdeleteObject against a denied path throws storage/unauthorized
Rules enforcementOrdinary SDK object paths are evaluated under Firebase Storage's canonical /b/{bucket}/o/{object} rules namespace while metadata preserves the ordinary object path
unit:storage/enforce.test.ts ("maps ordinary SDK object paths into the canonical bucket rules namespace"). Production's canonical /b/{bucket}/o/... namespace is independently captured on the storage-rules surface; this adapter mapping seam is unit-backed rather than presented as a production observation.pyric-admin/storage: File metadata and download URLs
The admin plane (surface storage-admin), climbing under CDD. Each row cites the production capture admin-storage-metadata-download-url (firebase-admin 13.10.0) and is replayed by the pyric-admin conformance suite on the in-process arm and on a SharedWorker host, and by the hosted replay on the Node host.
file.setMetadata(metadata) / file.getMetadata()setMetadata({ metadata: { key: value } }) stores custom metadata and advances metageneration; getMetadata() returns the keys under metadata, and a file saved without any has no metadata field
admin-storage-metadata-download-url (afterSave.customMetadata: null, afterSet.customMetadata.note: 'first', metagenerationAdvanced: true, setMetadataResolvesWithMetadata: true). All three match. (Structured evidence: oracle-conformance.test.ts, hosted-sqlite.test.ts)file.setMetadata({ metadata: { key: null } })A custom metadata key set to null is removed; the other keys, including firebaseStorageDownloadTokens, stay
admin-storage-metadata-download-url (nullRemovesKey.noteRemoved: true, nullRemovesKey.tokenKept: true). All three match. (Structured evidence: oracle-conformance.test.ts, hosted-sqlite.test.ts)getDownloadURL(file)Returns https://firebasestorage.googleapis.com/v0/b/<bucket>/o/<encoded path>?alt=media&token=<token>, whose token is the file's firebaseStorageDownloadTokens custom metadata. The Firebase metadata endpoint, which client SDKs read, reports the same token as downloadTokens and leaves it out of metadata
admin-storage-metadata-download-url records https://firebasestorage.googleapis.com/v0/b/<bucket>/o/<encoded path>?alt=media&token=<token>, the token equal to firebaseStorageDownloadTokens, and the Firebase metadata endpoint reporting it as downloadTokens outside metadata. On the Node host the hosted replay matches the path after the /__pyric/storage prefix, alt=media, the query keys, the token, and the client view's downloadTokens; the origin is the host's own http origin. In process and on a SharedWorker host there is no HTTP origin, so the URL is a data:<contentType>;base64,... URI that carries the bytes; the pyric-admin conformance suite pins it beside the production form. It diverges because only the Node host serves bytes over HTTP. (Structured evidence: oracle-conformance.test.ts, hosted-sqlite.test.ts)getDownloadURL(file)For a file without a download token, getDownloadURL mints a UUID into firebaseStorageDownloadTokens, and later calls keep it
admin-storage-metadata-download-url (afterSave.hasDownloadTokens: false; getDownloadURLWithoutToken: threw: false, mintsTokenIntoMetadata: true, mintedTokenIsUuid: true; the hosted replay also matches urlCarriesMintedToken: true). All three mint a UUID and keep it on later calls. (Structured evidence: oracle-conformance.test.ts, hosted-sqlite.test.ts)file.setMetadata({ metadata: { firebaseStorageDownloadTokens: null } })Removing firebaseStorageDownloadTokens revokes the download URL: a GET of it answers 403, and the next getDownloadURL mints a new token whose URL answers 200
admin-storage-metadata-download-url records revocation: tokenRemoved: true, revokedUrlStatus: 403, getDownloadURLAfterRevoke.mintsNewToken: true, newUrlStatus: 200. On the Node host the hosted replay matches all four. In process and on a SharedWorker host there is no HTTP origin, so a download URL is a data:<contentType>;base64,... URI that carries the bytes; removing the token and minting another match, but a data: URI cannot be revoked and still resolves, which the pyric-admin conformance suite pins beside the production status. (Structured evidence: hosted-sqlite.test.ts)GET <download URL>The download URL answers a GET with no credentials with the object's bytes and content type, and a Range request with 206 and Content-Range
admin-storage-metadata-download-url records unauthenticatedGet (200, audio/wav, bytesMatch: true) and rangeGet (206, bytes 2-5/64, bytesMatch: true). On the Node host the hosted replay matches both. In process and on a SharedWorker host there is no HTTP origin, so a download URL is a data:<contentType>;base64,... URI that carries the bytes; its GET matches, but it answers a Range request with 200 and every byte, which the pyric-admin conformance suite pins beside the production answer. (Structured evidence: oracle-conformance.test.ts, hosted-sqlite.test.ts)pyric-admin/storage: Bucket listing and prefix delete
The admin plane (surface storage-admin). firebase-admin’s Bucket.getFiles and Bucket.deleteFiles, as a backend calls them to clean up an entity’s objects under a prefix. The rows follow @google-cloud/storage 7.x and @google-cloud/paginator from their source and run on the in-process arm, a SharedWorker host, and the Node host. No production capture backs them yet, so they stay unverified.
bucket.getFiles({ prefix, delimiter, maxResults, pageToken, autoPaginate })Lists the files whose names start with prefix, in name order, as [files, nextQuery, apiResponse]. delimiter rolls names up into apiResponse.prefixes. maxResults or autoPaginate: false gives one page and the next page's query, or null on the last page; reading every page gives the call's own query in that position. apiResponse has no items, and the files carry no metadata until getMetadata
bucket-listing.test.ts pins prefix, delimiter, page, and result-tuple semantics as @google-cloud/storage 7.21 Bucket.getFiles and @google-cloud/paginator 5 run_ define them. bucket-files.test.ts runs the same queries on the in-process arm and on a SharedWorker host. The app scenario admin-storage-delete-prefix calls getFiles({ prefix }) from a firebase-admin backend under pyric sandbox --hosted. The remote arms read names with the host's storage.listAll, one folder at a time. (Structured evidence: scenario.ts)bucket.deleteFiles({ prefix, force })Deletes every file getFiles would list across its pages, up to maxResults, ten at a time, and leaves the others. Without force the first failed delete rejects the call; with force every file is tried and the call rejects with the array of errors
bucket-listing.test.ts pins force as @google-cloud/storage 7.21 Bucket.deleteFiles defines it: the first error without it, the array of errors with it. bucket-files.test.ts deletes a prefix on the in-process arm and on a SharedWorker host, and leaves other prefixes and buckets. The app scenario admin-storage-delete-prefix deletes a prefix from a firebase-admin backend under pyric sandbox --hosted and finds the other objects still there. (Structured evidence: scenario.ts)Calls in flight when the hosted connection drops
The web hosted client talks to the Node host over one WebSocket. When that socket drops, a call the socket had already taken is in flight: the host may or may not have run it (ADR-0019 decision 7). Each row here states what becomes of such a call, against what the production Web SDK does when its own connection drops.
Operations in flight at a hosted connection drop (web hosted client)A Storage operation (getMetadata, deleteObject, list, or an upload step) the web hosted client's socket had taken when it dropped fails once with unavailable and the message "The hosted sandbox connection was lost. Requests already sent may have completed; check state before retrying." It is not sent again. In production the Storage Web SDK retries a request that fails on the network with exponential backoff, for up to 2 minutes for an operation and 10 minutes for an upload, and then fails it with storage/retry-limit-exceeded.
@firebase/storage 0.14.3 dist/index.esm.js: DEFAULT_MAX_OPERATION_RETRY_TIME (2 minutes), DEFAULT_MAX_UPLOAD_RETRY_TIME (10 minutes), and retryLimitExceeded() in the request retry loop. packages/cli/test/serve/worker/hosted-reconnect-hold.test.ts drops a real loopback socket with storage.getMetadata and storage.deleteObject in flight and asserts each fails once with that message and reaches the host once.unavailable where production retries, then fails with storage/retry-limit-exceededClient SDKs in a registered server process
A server process started with node --import @pyric/cli/register and PYRIC_SANDBOX=remote, remote:<url>, 1 or true runs the client SDKs against the Node host (#1082): firebase/app, firebase/database, firebase/firestore, firebase/auth and firebase/storage resolve to @pyric/cli’s Node client, which reaches the host over its own hosted connection with the process’s own signed-in session, so the host’s rules apply as they do for any other client. Off the Node host every call fails instead of running against a private in-process sandbox, and the client services with no path to the host refuse. PYRIC_SANDBOX=local keeps the in-process sandbox. In production the client SDKs run in Node and reach the project.
getStorage(app) in a registered server processUnder a remote register activation on the Node host, firebase/storage in a server process uploads and reads the host's objects under its rules, over the host's byte route. An upload issued before the process's connection has attached waits for the attachment, keeps its place in the call order, and never sends its bytes as frames to a host that takes them only over the route; it fails as a held call does if the connection is not restored within 10 seconds. A finished upload does not keep the process up. When the host is not the Node host, every call fails with failed-precondition and a message naming the Node host (pyric sandbox --hosted or pyric({ hosted: true })); when no host is found, with the discovery error pyric-admin gets. No call falls back to an in-process sandbox.
test/apps/client-sdk-under-register runs the client SDKs under node --import @pyric/cli/register against a hosted Vite dev server, reads back with firebase-admin and a page, and asserts an upload issued as the process's first call that firebase-admin downloads, its HTTP download URL, and that a finished upload does not hold the process. storage-byte-route-settled.test.ts pins the wait, the call order and the deadline. On main (942cb175) it failed: the calls ran against a private in-process sandbox, so an upload returned a data: URL and firebase-admin read nothing they wrote. packages/cli/test/register/node-origin.test.ts runs the served surfaces under a Node origin whose host is not the Node host, or cannot be found, and asserts every call fails, useWorker stays true, the served app entry's placeholder sandbox stays empty, and a pyric/* mirror resolved from the app refuses. mapping.test.ts pins the mapping per activation value.. (Structured evidence: register-child.test.ts)Server-rendered modules under vite dev
Modules Vite loads for server rendering under vite dev with pyric() (server.ssrLoadModule, a runnable environment, a framework’s SSR entry and loaders) get the modules a registered server process gets (#1123): the client SDKs reach the dev server’s own Node host as one signed-in SSR session per dev server process, and firebase-admin reaches it as admin. This holds with Vite’s default externalization and with ssr.noExternal. A SharedWorker dev server refuses them, naming pyric({ hosted: true }), and a server environment Vite does not run in its own process (workerd) gets a module that throws when it loads. In production these modules run the Firebase SDKs in the server’s runtime and reach the project.
getStorage(app) in a server-rendered module under vite devOn a hosted dev server, firebase/storage in a server-rendered module uploads and reads the host's objects under its rules as the SSR session's user, over the host's byte route: an upload to another user's path fails with storage/unauthorized, and a download URL names the host's byte route. On a SharedWorker dev server every call fails with failed-precondition and a message naming pyric({ hosted: true }). No call reaches production or an in-process sandbox.
test/apps/vite-ssr-client-sdk uploads to the SSR user's own path, reads its download URL, is denied another user's path, and downloads the object with firebase-admin in a process on the host. On main (ba2c0bf0a) the scenario failed: SSR sign-in rejected with auth/network-request-failed from the network guard, and the RTDB, Firestore and Storage writes did not settle, because the imports loaded the real SDK. vite-module-swap.test.ts pins the routing per specifier, AI mode and environment (Vite 5's ssr option, a runnable environment, a non-runnable one), vite-ssr-activation.test.ts the host, the restart hand-over and the SharedWorker refusal, and vite-plugin-firestore.test.ts runs Vite with firebase installed, so it takes the externalized path. (Structured evidence: scenario.ts)initializeServerApp) is unsupportedCurrent gaps
Documented divergences
Known differences between Pyric and production Firebase. Each remains tracked as a non-conforming row.
getStorage(app, bucketUrl?)` / `getStorageSandbox(target, options?)getStorage(app, bucketUrl?) opens the bucket the URL names, with its own objects and the rules deployed to it; the app's default bucket is stored under the key pyric-default
unit:service.test.ts pins a bucket URL other than the app's storageBucket opening its own bucket, and the default bucket's store key pyric-default; unit:storage/per-bucket-rules.test.ts pins each bucket's objects and rules apart. test/apps/storage-per-bucket-rules uploads to the default bucket, gs://media-bucket and an undeployed bucket from the page on the Node host, the SharedWorker and the in-page sandbox, and from server scripts attached to the Node host and under PYRIC_SANDBOX=local, and each enforces the file firebase.json deploys to it (#1313). The in-page plane still reports the default bucket as pyric-default in metadata and references (#1519). (Structured evidence: storage-rules-install.test.ts, scenario.ts)ref(storage, '<origin>/__pyric/storage/v0/b/<bucket>/o/<path>')Production throws storage/invalid-url for a URL on the Node host's /__pyric/storage/v0/ route, as for any host it does not serve from. The sandbox reads the percent-decoded object path from <origin>/__pyric/storage/v0/b/<bucket>/o/<path> on any origin, as production does from its own download URL
client-storage-ref-urls (firebase 12.19.0) records pyricHostUrl (storage/invalid-url). The Node host's getDownloadURL issues this form, so an app that keeps a download URL and later calls deleteObject(ref(storage, url)) needs ref() to read it. The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(): both pin production's code beside the sandbox's reference, whose fullPath and name equal those production gives for firebaseDownloadUrl. The web byte route fixture in hosted-sqlite.test.ts keeps a download URL from the Node host and deletes the object by ref(storage, url), and hosted smoke test 9 does the same from a Chromium page against the built CLI's Node host. Production never issues this URL, so no production app depends on the error. (Structured evidence: oracle-conformance.test.ts)ref(storage, url).bucketProduction gives a reference on the URL's bucket, including a bucket other than the app's default. The sandbox's ref() keeps the handle's bucket, at the URL's path; getStorage(app, bucketUrl) reaches another bucket
client-storage-ref-urls (firebase 12.19.0) records gsOtherBucket and firebaseDownloadUrlOtherBucket (bucket: 'other-bucket') and gsDefaultBucket (bucket: 'b', the configured bucket). ref() keeps the handle's bucket: a URL naming another bucket reads that path in the handle's bucket. To reach another bucket, an app opens it with getStorage(app, bucketUrl) (storage#11). The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(): both pin production's other-bucket beside the sandbox's bucket and the URL's fullPath. (Structured evidence: oracle-conformance.test.ts)ref(storage, 'data:...')Production reads a string without ://, such as a data: URI, as an object path. The sandbox throws storage/invalid-url for a data: URI
client-storage-ref-urls (firebase 12.19.0) records dataUri (fullPath: 'data:audio/wav;base64,UklGRg==', name: 'wav;base64,UklGRg=='). In process and on a SharedWorker host, getDownloadURL returns a data: URI (storage#51), and no object exists at that literal path, so reading it as a path would make deleteObject(ref(storage, url)) resolve and delete nothing. The storage oracle suite replays it against the engine's ref(), and storage-ref-urls.test.ts against the served page client's ref(): both pin production's path beside the sandbox's storage/invalid-url, and the storage oracle suite shows a reference to a data: download URL throws while the object stays.uploadString(ref, value, format?, metadata?)Sandbox: format='base64url' (or any unknown format) rejected with storage/invalid-format naming the bad format. Prod: base64url is ACCEPTED (upload succeeds); a genuinely-unrecognized format throws storage/unknown
packages/conformance/observations/storage/storage-uploadstring-unknown-format.json: prod accepts base64url (base64urlOk: true) and throws storage/unknown for an unrecognized format — not storage/invalid-format. The v1 sandbox ships only raw/base64/data_url (matches StringFormat) and throws storage/invalid-format for anything else (ST-B3 replaced the old mis-parse-as-data_url behavior). Both sides pinned in oracle-conformance.test.ts; sandbox code path documented in upload.ts's decodeString. Implementing base64url decoding is still one line in decodeString. (Structured evidence: error-codes.test.ts)uploadBytesResumable(ref, data, metadata?)Exported by firebase/storage; returns an UploadTask with pause() / resume() / cancel()
unit:resumable-upload.test.ts confirms uploadBytesResumable(ref, data) returns an UploadTask supporting pause(), resume(), and cancel() over synthetic microtask steps.uploadBytesResumable(ref, data, metadata?)task.on('state_changed', next, error, complete) fires next with {bytesTransferred, totalBytes, state} snapshots
unit:resumable-upload.test.ts confirms synthetic progress snapshots are emitted during task execution without requiring network transfer.uploadBytesResumable(ref, data, metadata?)task.pause() flips state to 'paused'; task.resume() continues
unit:resumable-upload.test.ts confirms calling task.pause() and task.resume() transitions through 'paused' and 'running' states deterministically.uploadBytesResumable(ref, data, metadata?)task.cancel() rejects the upload with storage/canceled
unit:resumable-upload.test.ts confirms cancellation rejects with storage/canceled. A commit already sent cannot be recalled, so a cancel that races it rolls it back, then rejects and tells observers. Production never stores a canceled upload, so its rules never see the rollback: the commit takes a token bound to the client, the generation it stored, and the object it replaced, and the host, without the rules, puts that object back or deletes the new one in one generation-checked write, keeping any later write (#1157, #1159). storage-upload-rollback.test.ts pins the token's binding, the restore, and a cancel under rules that deny every delete; storage-ops.test.ts pins a commit settling after the cancel and one held while paused. The web byte route fixture in hosted-sqlite.test.ts and test/apps/client-sdk-under-register cancel under node --import @pyric/cli/register and read no object, or the earlier one after an overwrite; on main (8e1ee9cb4) the object stayed (#1137). A failed rollback rejects with its own code. The in-page task does the same (#1161), and storage-cancel-parity.test.ts compares the two. (Structured evidence: resumable-cancel-rollback.test.ts, scenario.ts, scenario.ts)getDownloadURL(ref)Exported by firebase/storage; returns a token-signed HTTPS URL that fetches the blob
storage-upload-bytes-roundtrip records urlIsHttps: true and a byte-identical fetch. The URL form depends on where the sandbox runs. On the Node host, getDownloadURL returns http://<host>/__pyric/storage/v0/b/<bucket>/o/<path>?alt=media&token=<token>: production's /v0/b/<bucket>/o/<path> path and alt=media query, under the host's own origin. The token is kept in the object's downloadTokens metadata, later calls return the same URL, it does not expire, and removing it from the metadata revokes the URL. A GET on the URL needs no header and serves Range. The hosted replay of the observation calls getDownloadURL and fetch through the web client against the host and its byte route, and matches downloadOk, bodyLen, and bytesMatch. The web byte route fixture pins token persistence and revocation, and hosted smoke test 8 streams and seeks an <audio> element by the URL in Chromium. In process and in a SharedWorker there is no HTTP origin to serve from, so getDownloadURL returns a data:<contentType>;base64,... URI that carries the object's bytes. The oracle replay proves its byte-identical fetch and asserts the data: prefix, and the client↔host integration proves SharedWorker mode returns the same form. The divergence is URL identity. The hosted URL is http on the local host's origin, under /__pyric/storage, where production's is https on Google Cloud Storage's host, so it is fetchable only where that host is reachable. The data: form has no token, no revocation, and no stable short string. Production observation admin-storage-metadata-download-url records the token itself: the Firebase metadata endpoint reports it as downloadTokens, firebase-admin sees it as the firebaseStorageDownloadTokens custom key, removing it makes the URL answer 403, and the URL answers Range with 206. (Structured evidence: hosted-sqlite.test.ts, smoke.pw.ts)deleteObject(ref)Sandbox: no-op on missing path (does NOT throw)
persistence.ts's delete. Prod's deleteObject on a missing path throws storage/object-not-found. Oracle-locked: packages/conformance/observations/storage/storage-delete-missing-throws.json (code: 'storage/object-not-found', name: 'FirebaseError' against digame-mas, fb-js-sdk 12.19.0). Both sides pinned in oracle-conformance.test.ts; documented in download.ts.getMetadata(ref)` / `updateMetadata(ref, metadata)updateMetadata with undefined field values preserves the prior value (does NOT clear it)
null to explicitly clear a field. Sandbox doesn't model null-clear (per metadata.ts doc comment). Documented; not probe-locked.getMetadata(ref)` / `updateMetadata(ref, metadata)FullMetadata.md5Hash populated on uploads
md5Hash. Oracle-locked: packages/conformance/observations/storage/storage-upload-then-getmetadata.json confirms prod sets md5Hash (hasMd5Hash: true after a vanilla uploadBytes). Both sides pinned in oracle-conformance.test.ts. Aligning the sandbox is a one-spot fix in upload.ts's buildStoredMetadata.getDownloadURL(file)Returns https://firebasestorage.googleapis.com/v0/b/<bucket>/o/<encoded path>?alt=media&token=<token>, whose token is the file's firebaseStorageDownloadTokens custom metadata. The Firebase metadata endpoint, which client SDKs read, reports the same token as downloadTokens and leaves it out of metadata
admin-storage-metadata-download-url records https://firebasestorage.googleapis.com/v0/b/<bucket>/o/<encoded path>?alt=media&token=<token>, the token equal to firebaseStorageDownloadTokens, and the Firebase metadata endpoint reporting it as downloadTokens outside metadata. On the Node host the hosted replay matches the path after the /__pyric/storage prefix, alt=media, the query keys, the token, and the client view's downloadTokens; the origin is the host's own http origin. In process and on a SharedWorker host there is no HTTP origin, so the URL is a data:<contentType>;base64,... URI that carries the bytes; the pyric-admin conformance suite pins it beside the production form. It diverges because only the Node host serves bytes over HTTP. (Structured evidence: oracle-conformance.test.ts, hosted-sqlite.test.ts)file.setMetadata({ metadata: { firebaseStorageDownloadTokens: null } })Removing firebaseStorageDownloadTokens revokes the download URL: a GET of it answers 403, and the next getDownloadURL mints a new token whose URL answers 200
admin-storage-metadata-download-url records revocation: tokenRemoved: true, revokedUrlStatus: 403, getDownloadURLAfterRevoke.mintsNewToken: true, newUrlStatus: 200. On the Node host the hosted replay matches all four. In process and on a SharedWorker host there is no HTTP origin, so a download URL is a data:<contentType>;base64,... URI that carries the bytes; removing the token and minting another match, but a data: URI cannot be revoked and still resolves, which the pyric-admin conformance suite pins beside the production status. (Structured evidence: hosted-sqlite.test.ts)GET <download URL>The download URL answers a GET with no credentials with the object's bytes and content type, and a Range request with 206 and Content-Range
admin-storage-metadata-download-url records unauthenticatedGet (200, audio/wav, bytesMatch: true) and rangeGet (206, bytes 2-5/64, bytesMatch: true). On the Node host the hosted replay matches both. In process and on a SharedWorker host there is no HTTP origin, so a download URL is a data:<contentType>;base64,... URI that carries the bytes; its GET matches, but it answers a Range request with 200 and every byte, which the pyric-admin conformance suite pins beside the production answer. (Structured evidence: oracle-conformance.test.ts, hosted-sqlite.test.ts)Operations in flight at a hosted connection drop (web hosted client)A Storage operation (getMetadata, deleteObject, list, or an upload step) the web hosted client's socket had taken when it dropped fails once with unavailable and the message "The hosted sandbox connection was lost. Requests already sent may have completed; check state before retrying." It is not sent again. In production the Storage Web SDK retries a request that fails on the network with exponential backoff, for up to 2 minutes for an operation and 10 minutes for an upload, and then fails it with storage/retry-limit-exceeded.
@firebase/storage 0.14.3 dist/index.esm.js: DEFAULT_MAX_OPERATION_RETRY_TIME (2 minutes), DEFAULT_MAX_UPLOAD_RETRY_TIME (10 minutes), and retryLimitExceeded() in the request retry loop. packages/cli/test/serve/worker/hosted-reconnect-hold.test.ts drops a real loopback socket with storage.getMetadata and storage.deleteObject in flight and asserts each fails once with that message and reaches the host once.getStorage(app) in a registered server processUnder a remote register activation on the Node host, firebase/storage in a server process uploads and reads the host's objects under its rules, over the host's byte route. An upload issued before the process's connection has attached waits for the attachment, keeps its place in the call order, and never sends its bytes as frames to a host that takes them only over the route; it fails as a held call does if the connection is not restored within 10 seconds. A finished upload does not keep the process up. When the host is not the Node host, every call fails with failed-precondition and a message naming the Node host (pyric sandbox --hosted or pyric({ hosted: true })); when no host is found, with the discovery error pyric-admin gets. No call falls back to an in-process sandbox.
test/apps/client-sdk-under-register runs the client SDKs under node --import @pyric/cli/register against a hosted Vite dev server, reads back with firebase-admin and a page, and asserts an upload issued as the process's first call that firebase-admin downloads, its HTTP download URL, and that a finished upload does not hold the process. storage-byte-route-settled.test.ts pins the wait, the call order and the deadline. On main (942cb175) it failed: the calls ran against a private in-process sandbox, so an upload returned a data: URL and firebase-admin read nothing they wrote. packages/cli/test/register/node-origin.test.ts runs the served surfaces under a Node origin whose host is not the Node host, or cannot be found, and asserts every call fails, useWorker stays true, the served app entry's placeholder sandbox stays empty, and a pyric/* mirror resolved from the app refuses. mapping.test.ts pins the mapping per activation value.. (Structured evidence: register-child.test.ts)getStorage(app) in a server-rendered module under vite devOn a hosted dev server, firebase/storage in a server-rendered module uploads and reads the host's objects under its rules as the SSR session's user, over the host's byte route: an upload to another user's path fails with storage/unauthorized, and a download URL names the host's byte route. On a SharedWorker dev server every call fails with failed-precondition and a message naming pyric({ hosted: true }). No call reaches production or an in-process sandbox.
test/apps/vite-ssr-client-sdk uploads to the SSR user's own path, reads its download URL, is denied another user's path, and downloads the object with firebase-admin in a process on the host. On main (ba2c0bf0a) the scenario failed: SSR sign-in rejected with auth/network-request-failed from the network guard, and the RTDB, Firestore and Storage writes did not settle, because the imports loaded the real SDK. vite-module-swap.test.ts pins the routing per specifier, AI mode and environment (Vite 5's ssr option, a runnable environment, a non-runnable one), vite-ssr-activation.test.ts the host, the restart hand-over and the SharedWorker refusal, and vite-plugin-firestore.test.ts runs Vite with firebase installed, so it takes the externalized path. (Structured evidence: scenario.ts)Not implemented yet
Tracked behavior that is not implemented in the current contract.
getStream(ref, maxDownloadSize?)Exported by firebase/storage (Node entry only); returns a Node Readable
pyric/storage implementation or behavioral probe exists; availability is classified by the owning surface contract.list(ref, options?)Exported by firebase/storage; accepts { maxResults, pageToken }, returns a ListResult with nextPageToken set when more pages remain
list implementation or behavioral probe exists; availability is classified by the owning surface contract. ListResult.nextPageToken remains optional for forward-compatible consumer code.getMetadata(ref)` / `updateMetadata(ref, metadata)FullMetadata.ref lazy population (prod populates lazily)
pyric/storage — metadata.ts explicitly omits ref from FullMetadataconnectStorageEmulator(storage, host, port)Exported by firebase/storage; reroutes a FirebaseStorage handle to a local emulator
pyric/storage — the sandbox IS the local-target alternative; emulator parity is out of scope per index.tsUnverified
Tracked behavior whose available evidence does not yet establish the production result.
bucket.getFiles({ prefix, delimiter, maxResults, pageToken, autoPaginate })Lists the files whose names start with prefix, in name order, as [files, nextQuery, apiResponse]. delimiter rolls names up into apiResponse.prefixes. maxResults or autoPaginate: false gives one page and the next page's query, or null on the last page; reading every page gives the call's own query in that position. apiResponse has no items, and the files carry no metadata until getMetadata
bucket-listing.test.ts pins prefix, delimiter, page, and result-tuple semantics as @google-cloud/storage 7.21 Bucket.getFiles and @google-cloud/paginator 5 run_ define them. bucket-files.test.ts runs the same queries on the in-process arm and on a SharedWorker host. The app scenario admin-storage-delete-prefix calls getFiles({ prefix }) from a firebase-admin backend under pyric sandbox --hosted. The remote arms read names with the host's storage.listAll, one folder at a time. (Structured evidence: scenario.ts)bucket.deleteFiles({ prefix, force })Deletes every file getFiles would list across its pages, up to maxResults, ten at a time, and leaves the others. Without force the first failed delete rejects the call; with force every file is tried and the call rejects with the array of errors
bucket-listing.test.ts pins force as @google-cloud/storage 7.21 Bucket.deleteFiles defines it: the first error without it, the array of errors with it. bucket-files.test.ts deletes a prefix on the in-process arm and on a SharedWorker host, and leaves other prefixes and buckets. The app scenario admin-storage-delete-prefix deletes a prefix from a firebase-admin backend under pyric sandbox --hosted and finds the other objects still there. (Structured evidence: scenario.ts)Reviewed public-runtime gaps
storage.node-streamThe Node-stream variant is deferred — not part of the browser-shaped v1 scope yet, but not genuinely un-modelable.
getStreamstorage.paginated-listingPaginated listing is deferred — listAll covers the v1 scope; pagination needs a stable pageToken shape, which is unbuilt design work rather than a sandbox limitation.
list