Initial Commit

packages/persistence/storage/storage-uri-plugin-fallback/src/ops/metadata.md

@@ -0,0 +1,60 @@
+# ops/metadata
+
+## Purpose
+
+The `ops/metadata` module hosts `fallbackExists` and `fallbackStat`, the
+metadata-side adapter operations. Both walk the candidate list
+sequentially and return as soon as a candidate produces an authoritative
+answer. Failures fall through cleanly: `exists` resolves `false` when no
+candidate confirms presence, and `stat` resolves `undefined` when no
+candidate can answer cheaply.
+
+## Features
+
+- Sequential walk with first-truthy semantics for `exists`.
+- Sequential walk returning the first defined `StatResult` for `stat`.
+- Soft failures: aggregate exhaustion does not raise, mirroring the
+  semantics of `StorageLike.exists`.
+- Recursion-context propagation via the shared `DepthContext`.
+
+## Usage: Basic Example
+
+```ts
+import {
+    fallbackExists,
+    fallbackStat,
+} from "@suaveplan/storage-uri-plugin-fallback/ops";
+
+const present = await fallbackExists(uri, ctx, deps, signal);
+const meta = await fallbackStat(uri, ctx, deps, signal);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fallbackStat } from "@suaveplan/storage-uri-plugin-fallback/ops";
+
+const meta = await fallbackStat(
+    uri,
+    ctx,
+    { resolver, policy: { ...policy, errorClass: "any" }, events },
+    signal,
+);
+if (meta?.etag) console.log("etag:", meta.etag);
+```
+
+## API Reference
+
+- `fallbackExists(uri, ctx, deps, signal): Promise<boolean>`
+- `fallbackStat(uri, ctx, deps, signal): Promise<StatResult | undefined>`
+- `MetadataDeps` — `{ resolver, policy, events }`.
+
+## Implementation Notes
+
+Both functions internally throw a sentinel error when a candidate
+answers "no" or "no-stat" so the shared walk machinery treats the leg as
+a transient failure and continues. The outer `try/catch` collapses the
+walk-exhausted `ALL_CANDIDATES_FAILED` into the soft return values the
+`StorageLike` contract expects from these methods.
+
+This module is part of the universal fallback URI plugin family. It coordinates with the recursion, walk, ops, observability, and classification modules through small, narrowly-typed value contracts. The implementation deliberately keeps surface area small so each piece can be substituted or instrumented independently without touching consumers. Refer to the package README for the end-to-end picture and to the spec delta for the requirement matrix this module helps satisfy.