first commit

docs/persistence/storage/storage-uri-plugin-fallback/src/classify/classify.md

@@ -0,0 +1,66 @@
+# classify
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `classify` module hosts the pure error-classification function that
+governs fall-through eligibility for every walk strategy. It maps an
+arbitrary throwable into one of three classes — `"transient"`,
+`"semantic"`, or `"abort"` — based on the error's namespaced code, its
+shape (`AbortError` name), and the configured `FallbackPolicy.errorClass`
+knob. The function is deterministic and side-effect-free.
+
+## Features
+
+- Recognises `STORAGE_URI.ABORTED` and `FALLBACK_URI.ABORTED` as
+  `"abort"`.
+- Treats `MAX_DEPTH_EXCEEDED` and `CIRCULAR_REFERENCE` as `"semantic"`
+  regardless of policy (programmer-bug surfaces must not silently fall
+  through).
+- Maps `STORAGE_URI.ADAPTER_ERROR` and `STORAGE_URI.NOT_FOUND` to
+  `"transient"` by default.
+- Treats other `STORAGE_URI.*` semantic codes (UNKNOWN_SCHEME,
+  INVALID_URI, WRITE_UNSUPPORTED, LIST_UNSUPPORTED, SCHEME_CONFLICT) as
+  `"semantic"` under default policy and `"transient"` under
+  `errorClass: "any"`.
+
+## Usage: Basic Example
+
+```ts
+import { classify } from "@suaveplan/storage-uri-plugin-fallback/classify";
+
+const klass = classify(err, policy);
+if (klass === "abort") throw err;
+```
+
+## Usage: Advanced Example
+
+```ts
+import { classify } from "@suaveplan/storage-uri-plugin-fallback/classify";
+import { FallbackPolicySchema } from "@suaveplan/storage-uri-plugin-fallback/types";
+
+const relaxed = FallbackPolicySchema.parse({ errorClass: "any" });
+for (const err of collected) {
+    if (classify(err, relaxed) === "transient") continue;
+    throw err;
+}
+```
+
+## API Reference
+
+- `ErrorClass` — `"transient" | "semantic" | "abort"`.
+- `classify(err: unknown, policy: FallbackPolicy): ErrorClass`.
+
+## Implementation Notes
+
+The classifier never re-throws; callers own the decision to surface or
+swallow. Unknown thrown values default to `"transient"` because the
+resolver normalises foreign throwables into `STORAGE_URI.ADAPTER_ERROR`
+upstream of the walk, so the unknown branch is a safety net for
+deliberately bypassed paths (e.g. a candidate plugin that throws a plain
+`Error` synchronously inside its `parse`).
+
+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.