@bandeira-tech/b3nd-save 0.8.1 → 0.13.1

package/esm/url.d.ts

@@ -9,24 +9,46 @@
  * (memory, postgres, mongo, sqlite, fs, ipfs, s3, elasticsearch,
  * localstorage, indexeddb) honor the grammar defined here.
  *
- * A **url** = a uri (the canonical resource identifier) plus a query
- * string of read parameters. The uri is the routing identity used for
- * storage keys and observe-match keys. The query string carries
- * request-time-only directives that shape the response without
- * changing identity.
+ * A **url** = a uri (the canonical resource identifier, possibly carrying
+ * wildcards in its path) plus a query string of read parameters. The
+ * literal portion of the uri (everything before the first wildcard) is
+ * the routing identity used for storage keys and observe-match keys.
+ * The query string carries request-time-only directives that shape the
+ * response without changing identity.
  *
- * Grammar:
+ * Grammar (v2 — see `.cc-chat/20260625121936-grammar-shape/output.md`):
  *
- *     <uri>[?fn=<fn>][&<param>=<value>...][&x-<ns>.<key>=<value>...]
+ *     <uri-with-glob>[?fn=<fn>][&<param>=<value>...][&x-<ns>.<key>=<value>...]
+ *
+ * Glob tokens in `<uri-with-glob>`'s path:
+ * - `?`  exactly one non-`/` character
+ * - `*`  zero or more non-`/` characters (one segment)
+ * - `**` zero or more segments (any chars including `/`); **find-only**
  *
  * Reserved `fn` values:
- * - `read`   — point read (default for non-trailing-slash uris)
- * - `ls`     — list under a prefix (default when uri ends with `/`)
- * - `count`  — count of entries under a prefix
+ * - `read`   — point read (default for bare uris)
+ * - `ls`     — list direct children (URI has `?`/`*` but no `**`)
+ * - `find`   — recursive walk (URI contains `**`)
+ * - `count`  — count of entries
  * - `x-*.*`  — provider-defined extension functions
  *
+ * Validation rules (§3.4 — silent-default-trap mitigation):
+ * - A URI with wildcards in its path MUST carry an explicit `?fn=`.
+ * - `?fn=ls` rejects URIs containing `**`.
+ * - `?fn=find` requires `**` (or a legacy `?pattern=` carrying `**`).
+ * - `?fn=count` accepts any URI shape.
+ * - A bare URI (no wildcards) keeps today's behavior — `?fn=` may be
+ *   omitted; defaults to `read` (no trailing slash) or `ls` (trailing
+ *   slash, equivalent to `<uri>*?fn=ls`).
+ *
+ * Dual-accept transition: `?pattern=<glob>` still parses (logged as
+ * deprecated once per process). Internally normalized to the same
+ * `{prefix, glob}` shape as the URI-embedded form. Removal scheduled
+ * one minor version out.
+ *
  * Standard params (meaningful only for some fns; stores ignore the rest):
- * `limit`, `page`, `cursor`, `sortBy`, `sortOrder`, `pattern`, `format`.
+ * `limit`, `page`, `cursor`, `sortBy`, `sortOrder`, `pattern`, `format`,
+ * `fields`.
  *
  * Anything matching `x-<ns>.<key>` lands in the `ext` map and is passed
  * opaquely to the executing store. Callers inspect ext entries by
@@ -44,12 +66,22 @@ export interface ReadParams {
     sortOrder?: string;
     pattern?: string;
     format?: string;
+    /**
+     * Comma-separated list of field names to project from each returned
+     * record. Applies to `fn=read` and `fn=ls&format=full`. Fields not
+     * declared in the entity meta are silently absent from the
+     * projection — the store does not error on unknown projection
+     * fields, they simply do not appear. `format=uris` ignores `fields`
+     * since it returns no record payloads.
+     */
+    fields?: string[];
 }
 /**
  * A parsed url decomposed into routing identity (`uri`), function
  * (`fn`), standard read parameters (`params`), and the `x-*` extension
  * bag (`ext`), plus the structural fields shared with WHATWG URL
- * (`protocol`, `hostname`, `path`, `program`).
+ * (`protocol`, `hostname`, `path`, `program`), plus the v2 glob split
+ * (`glob`).
  */
 export interface ParsedUrl {
     /** Scheme without trailing `://` (e.g. `"mutable"`, `"b3nd"`). */
@@ -60,15 +92,64 @@ export interface ParsedUrl {
     path: string;
     /** `protocol://hostname` — the routing root above the path. */
     program: string;
-    /** Full routing identity: `program` + `path`. Query is stripped. */
+    /**
+     * Routing identity. When the source url contains no wildcards in its
+     * path, this is the full URI as written. When the source contains
+     * wildcards, this is the **literal prefix** — everything before the
+     * first wildcard segment, including the trailing `/`. Backends key
+     * storage / observe matching off this value.
+     */
     uri: string;
-    /** Reserved fn (`read`/`ls`/`count`) or `x-<ns>.<name>` extension. */
+    /**
+     * Glob tail extracted from the source URI's path (v2 §3.3). Empty
+     * string when the source carried no wildcards in its path. When the
+     * caller used the dual-accept `?pattern=` form, this carries that
+     * value verbatim (back-compat normalization).
+     */
+    glob: string;
+    /** Reserved fn (`read`/`ls`/`find`/`count`) or `x-<ns>.<name>` extension. */
     fn: string;
-    /** Standard read params (numeric ones coerced). */
+    /**
+     * Standard read params. `params.pattern` is populated from either
+     * the URI-embedded glob (preferred) or the legacy `?pattern=` query
+     * param (deprecated) — both end up here so call sites that read
+     * `params.pattern` keep working through the transition.
+     */
     params: ReadParams;
     /** Bag of `x-*` extension query params (every key starts with `x-`). */
     ext: Record<string, string>;
 }
+/**
+ * Split a uri's path into its literal prefix and its glob tail.
+ *
+ * Walks the path looking for the first segment that contains a glob
+ * metacharacter (`*` or `?`). Returns the literal prefix (everything
+ * up to and including the `/` before that segment) and the glob tail
+ * (the wildcard segment and everything after it). When no wildcards
+ * are present, returns the whole URI as `prefix` and `""` as `glob`.
+ *
+ * The walk is path-aware so `?` is treated as a wildcard inside path
+ * segments only (the function never sees a query string — callers
+ * strip `?<query>` first).
+ *
+ * Examples:
+ *   "x://a/b/c"        → { prefix: "x://a/b/c",  glob: "" }
+ *   "x://a/b/**"       → { prefix: "x://a/b/",   glob: "**" }
+ *   "x://a/**\/x.md"   → { prefix: "x://a/",     glob: "**\/x.md" }
+ *   "x://a/al*"        → { prefix: "x://a/",     glob: "al*" }
+ *   "x://a/al?"        → { prefix: "x://a/",     glob: "al?" }
+ *   "**"               → { prefix: "",           glob: "**" }
+ *
+ * Note: the input must already have `?<query>` stripped — the function
+ * has no way to distinguish a literal `?` in the path from a query
+ * separator. `parseUrl` handles the split before calling.
+ */
+export declare function splitLocatorGlob(uri: string): {
+    prefix: string;
+    glob: string;
+};
+/** Test-only hook to reset the deprecation gate between tests. */
+export declare function _resetPatternDeprecationLogForTests(): void;
 /**
  * Parse a url into its structural fields, function, params, and extensions.
  *
@@ -77,11 +158,23 @@ export interface ParsedUrl {
  * (e.g. `b3nd://count/mutable://users/`) stays inside `path` — no
  * special-casing.
  *
- * Defaults:
- * - `fn=read` for uris without a trailing slash
- * - `fn=ls` for uris with a trailing slash
+ * Glob extraction: the path is scanned for the first wildcard segment
+ * (`splitLocatorGlob`). When wildcards are present, `parsed.uri` is the
+ * literal prefix; `parsed.glob` is the wildcard tail; `parsed.params.pattern`
+ * is set to the glob so downstream code can read either field. When the
+ * caller used the legacy `?pattern=` form instead, the same fields are
+ * populated and a deprecation is logged once per process.
  *
- * Numeric params (`limit`, `page`) are coerced; throws on NaN.
+ * Verb defaults & validation (v2 §3.4):
+ * - bare URI (no wildcards), no `?fn=` → defaults to `read` for non-
+ *   trailing-slash, `ls` for trailing-slash (legacy convenience)
+ * - any URI with wildcards in the path → `?fn=` is REQUIRED
+ * - `**` in the URI is valid only under `?fn=find` (or `?fn=count`)
+ * - `*`/`?` (no `**`) is valid under `?fn=ls` or `?fn=find` or `?fn=count`
+ * - `?fn=count` accepts any URI shape
+ *
+ * Numeric params (`limit`, `page`) are coerced; throws on NaN. Unknown
+ * standard params throw.
  */
 export declare function parseUrl(url: string): ParsedUrl;
 /**
@@ -91,6 +184,12 @@ export declare function parseUrl(url: string): ParsedUrl;
  *
  * Omits `fn=` when it matches the trailing-slash default. Throws if any
  * `ext` key does not start with `x-`.
+ *
+ * Note: `buildUrl` writes the URI verbatim — it does not splice a glob
+ * back into the path. Callers that have a `ParsedUrl` produced by
+ * `parseUrl` from a URI-embedded-glob source should reconstruct the
+ * full url manually if they need to round-trip the original string; the
+ * cheap path is `<originalUrl>` which they already have.
  */
 export declare function buildUrl(parsed: {
     uri: string;
@@ -103,6 +202,10 @@ export declare function buildUrl(parsed: {
  * request-time-only and never participates in routing or storage
  * keying. Cheap helper for stores and callers that need the bare uri
  * without paying for full parse.
+ *
+ * Note: this returns the URI as written, **including** any embedded
+ * glob (`<uri-with-glob>`). For just the literal routing prefix, parse
+ * the url and read `parsed.uri`.
  */
 export declare function uriOf(url: string): string;
 //# sourceMappingURL=url.d.ts.map

package/esm/url.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAIH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,mDAAmD;IACnD,MAAM,EAAE,UAAU,CAAC;IACnB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CA8D/C;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,GAAG,MAAM,CAwBT;AAED;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGzC"}
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAIH;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,MAAM,EAAE,UAAU,CAAC;IACnB,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,GACV;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAuClC;AAcD,kEAAkE;AAClE,wBAAgB,mCAAmC,IAAI,IAAI,CAE1D;AAID;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAkJ/C;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B,GAAG,MAAM,CAwBT;AAED;;;;;;;;;GASG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGzC"}

package/esm/url.js

@@ -9,29 +9,129 @@
  * (memory, postgres, mongo, sqlite, fs, ipfs, s3, elasticsearch,
  * localstorage, indexeddb) honor the grammar defined here.
  *
- * A **url** = a uri (the canonical resource identifier) plus a query
- * string of read parameters. The uri is the routing identity used for
- * storage keys and observe-match keys. The query string carries
- * request-time-only directives that shape the response without
- * changing identity.
+ * A **url** = a uri (the canonical resource identifier, possibly carrying
+ * wildcards in its path) plus a query string of read parameters. The
+ * literal portion of the uri (everything before the first wildcard) is
+ * the routing identity used for storage keys and observe-match keys.
+ * The query string carries request-time-only directives that shape the
+ * response without changing identity.
  *
- * Grammar:
+ * Grammar (v2 — see `.cc-chat/20260625121936-grammar-shape/output.md`):
  *
- *     <uri>[?fn=<fn>][&<param>=<value>...][&x-<ns>.<key>=<value>...]
+ *     <uri-with-glob>[?fn=<fn>][&<param>=<value>...][&x-<ns>.<key>=<value>...]
+ *
+ * Glob tokens in `<uri-with-glob>`'s path:
+ * - `?`  exactly one non-`/` character
+ * - `*`  zero or more non-`/` characters (one segment)
+ * - `**` zero or more segments (any chars including `/`); **find-only**
  *
  * Reserved `fn` values:
- * - `read`   — point read (default for non-trailing-slash uris)
- * - `ls`     — list under a prefix (default when uri ends with `/`)
- * - `count`  — count of entries under a prefix
+ * - `read`   — point read (default for bare uris)
+ * - `ls`     — list direct children (URI has `?`/`*` but no `**`)
+ * - `find`   — recursive walk (URI contains `**`)
+ * - `count`  — count of entries
  * - `x-*.*`  — provider-defined extension functions
  *
+ * Validation rules (§3.4 — silent-default-trap mitigation):
+ * - A URI with wildcards in its path MUST carry an explicit `?fn=`.
+ * - `?fn=ls` rejects URIs containing `**`.
+ * - `?fn=find` requires `**` (or a legacy `?pattern=` carrying `**`).
+ * - `?fn=count` accepts any URI shape.
+ * - A bare URI (no wildcards) keeps today's behavior — `?fn=` may be
+ *   omitted; defaults to `read` (no trailing slash) or `ls` (trailing
+ *   slash, equivalent to `<uri>*?fn=ls`).
+ *
+ * Dual-accept transition: `?pattern=<glob>` still parses (logged as
+ * deprecated once per process). Internally normalized to the same
+ * `{prefix, glob}` shape as the URI-embedded form. Removal scheduled
+ * one minor version out.
+ *
  * Standard params (meaningful only for some fns; stores ignore the rest):
- * `limit`, `page`, `cursor`, `sortBy`, `sortOrder`, `pattern`, `format`.
+ * `limit`, `page`, `cursor`, `sortBy`, `sortOrder`, `pattern`, `format`,
+ * `fields`.
  *
  * Anything matching `x-<ns>.<key>` lands in the `ext` map and is passed
  * opaquely to the executing store. Callers inspect ext entries by
  * their flat string key (e.g. `ext["x-feed.cursor"]`).
  */
+/**
+ * Split a uri's path into its literal prefix and its glob tail.
+ *
+ * Walks the path looking for the first segment that contains a glob
+ * metacharacter (`*` or `?`). Returns the literal prefix (everything
+ * up to and including the `/` before that segment) and the glob tail
+ * (the wildcard segment and everything after it). When no wildcards
+ * are present, returns the whole URI as `prefix` and `""` as `glob`.
+ *
+ * The walk is path-aware so `?` is treated as a wildcard inside path
+ * segments only (the function never sees a query string — callers
+ * strip `?<query>` first).
+ *
+ * Examples:
+ *   "x://a/b/c"        → { prefix: "x://a/b/c",  glob: "" }
+ *   "x://a/b/**"       → { prefix: "x://a/b/",   glob: "**" }
+ *   "x://a/**\/x.md"   → { prefix: "x://a/",     glob: "**\/x.md" }
+ *   "x://a/al*"        → { prefix: "x://a/",     glob: "al*" }
+ *   "x://a/al?"        → { prefix: "x://a/",     glob: "al?" }
+ *   "**"               → { prefix: "",           glob: "**" }
+ *
+ * Note: the input must already have `?<query>` stripped — the function
+ * has no way to distinguish a literal `?` in the path from a query
+ * separator. `parseUrl` handles the split before calling.
+ */
+export function splitLocatorGlob(uri) {
+    // Find the scheme boundary; wildcards before the path are nonsense
+    // but we don't reject them here — splitLocatorGlob is a pure
+    // structural split. The caller (parseUrl) sees the result and the
+    // grammar validator decides what's legal.
+    const schemeIdx = uri.indexOf("://");
+    let pathStart;
+    if (schemeIdx < 0) {
+        pathStart = 0;
+    }
+    else {
+        const rest = uri.slice(schemeIdx + 3);
+        const slash = rest.indexOf("/");
+        pathStart = slash < 0 ? uri.length : schemeIdx + 3 + slash;
+    }
+    // Walk segment by segment from pathStart. A segment containing `*`
+    // or `?` is the first wildcard segment; the split point is the `/`
+    // that begins that segment.
+    let segStart = pathStart;
+    const len = uri.length;
+    for (let i = pathStart; i <= len; i++) {
+        if (i === len || uri.charCodeAt(i) === 47 /* / */) {
+            const seg = uri.slice(segStart, i);
+            if (seg.includes("*") || seg.includes("?")) {
+                // Prefix is everything up to (and including) the `/` before
+                // this segment. segStart points at the first char of the
+                // segment, so prefix = uri.slice(0, segStart). When the
+                // wildcard segment is at the root (no preceding `/`),
+                // segStart === pathStart and prefix is just the program.
+                return {
+                    prefix: uri.slice(0, segStart),
+                    glob: uri.slice(segStart),
+                };
+            }
+            segStart = i + 1;
+        }
+    }
+    return { prefix: uri, glob: "" };
+}
+// ── Deprecation log gate ────────────────────────────────────────────
+let _patternDeprecationLogged = false;
+function logPatternDeprecationOnce() {
+    if (_patternDeprecationLogged)
+        return;
+    _patternDeprecationLogged = true;
+    console.warn("b3nd-save: `?pattern=` query param is deprecated; use URI-embedded glob " +
+        '(e.g. "<root>/**?fn=find"). Support will be removed one minor version out.');
+}
+/** Test-only hook to reset the deprecation gate between tests. */
+export function _resetPatternDeprecationLogForTests() {
+    _patternDeprecationLogged = false;
+}
+// ── Parser ───────────────────────────────────────────────────────────
 /**
  * Parse a url into its structural fields, function, params, and extensions.
  *
@@ -40,23 +140,35 @@
  * (e.g. `b3nd://count/mutable://users/`) stays inside `path` — no
  * special-casing.
  *
- * Defaults:
- * - `fn=read` for uris without a trailing slash
- * - `fn=ls` for uris with a trailing slash
+ * Glob extraction: the path is scanned for the first wildcard segment
+ * (`splitLocatorGlob`). When wildcards are present, `parsed.uri` is the
+ * literal prefix; `parsed.glob` is the wildcard tail; `parsed.params.pattern`
+ * is set to the glob so downstream code can read either field. When the
+ * caller used the legacy `?pattern=` form instead, the same fields are
+ * populated and a deprecation is logged once per process.
  *
- * Numeric params (`limit`, `page`) are coerced; throws on NaN.
+ * Verb defaults & validation (v2 §3.4):
+ * - bare URI (no wildcards), no `?fn=` → defaults to `read` for non-
+ *   trailing-slash, `ls` for trailing-slash (legacy convenience)
+ * - any URI with wildcards in the path → `?fn=` is REQUIRED
+ * - `**` in the URI is valid only under `?fn=find` (or `?fn=count`)
+ * - `*`/`?` (no `**`) is valid under `?fn=ls` or `?fn=find` or `?fn=count`
+ * - `?fn=count` accepts any URI shape
+ *
+ * Numeric params (`limit`, `page`) are coerced; throws on NaN. Unknown
+ * standard params throw.
  */
 export function parseUrl(url) {
     const qIdx = url.indexOf("?");
-    const uri = qIdx < 0 ? url : url.slice(0, qIdx);
+    const uriRaw = qIdx < 0 ? url : url.slice(0, qIdx);
     const query = qIdx < 0 ? "" : url.slice(qIdx + 1);
-    const schemeIdx = uri.indexOf("://");
+    const schemeIdx = uriRaw.indexOf("://");
     let protocol = "";
     let hostname = "";
     let path = "";
     if (schemeIdx >= 0) {
-        protocol = uri.slice(0, schemeIdx);
-        const rest = uri.slice(schemeIdx + 3);
+        protocol = uriRaw.slice(0, schemeIdx);
+        const rest = uriRaw.slice(schemeIdx + 3);
         const slash = rest.indexOf("/");
         if (slash < 0) {
             hostname = rest;
@@ -68,13 +180,13 @@ export function parseUrl(url) {
         }
     }
     else {
-        path = uri;
+        path = uriRaw;
     }
     const program = protocol ? `${protocol}://${hostname}` : "";
+    // Split off any glob tail embedded in the path.
+    const { prefix: uriPrefix, glob: uriGlob } = splitLocatorGlob(uriRaw);
     const sp = new URLSearchParams(query);
     const explicitFn = sp.get("fn") ?? undefined;
-    const defaultFn = uri.endsWith("/") ? "ls" : "read";
-    const fn = explicitFn ?? defaultFn;
     const params = {};
     const ext = {};
     for (const [key, value] of sp.entries()) {
@@ -97,15 +209,87 @@ export function parseUrl(url) {
             case "cursor":
             case "sortBy":
             case "sortOrder":
-            case "pattern":
             case "format":
                 params[key] = value;
                 break;
+            case "pattern":
+                params.pattern = value;
+                break;
+            case "fields":
+                params.fields = value.split(",").map((f) => f.trim()).filter(Boolean);
+                break;
             default:
                 throw new Error(`Unknown read param: ${key}`);
         }
     }
-    return { protocol, hostname, path, program, uri, fn, params, ext };
+    // Reconcile URI-embedded glob with legacy `?pattern=`.
+    // Both populated → conflict → throw (caller has two intents in one URL).
+    // Only `?pattern=` populated → dual-accept transition; log deprecation;
+    //   leave `parsed.uri` as the literal uriRaw (it has no wildcards) and
+    //   `parsed.glob` carries the pattern value (the routing identity is
+    //   still the literal uri).
+    // Only URI glob populated → preferred path; mirror into params.pattern
+    //   so legacy push-down sites that read `params.pattern` keep working.
+    let effectiveGlob = uriGlob;
+    let effectiveUri = uriPrefix;
+    if (uriGlob && params.pattern !== undefined) {
+        throw new Error(`b3nd-save: cannot combine URI-embedded glob ("${uriGlob}") with ` +
+            `?pattern= query param ("${params.pattern}") — pick one`);
+    }
+    if (!uriGlob && params.pattern !== undefined) {
+        logPatternDeprecationOnce();
+        effectiveGlob = params.pattern;
+        effectiveUri = uriRaw;
+    }
+    if (uriGlob && params.pattern === undefined) {
+        params.pattern = uriGlob;
+    }
+    // Verb resolution. The default lookup uses the literal-uri shape
+    // (trailing slash → ls else read) but is only honoured when there
+    // are no wildcards anywhere.
+    const hasWildcards = effectiveGlob.length > 0;
+    let fn;
+    if (explicitFn !== undefined) {
+        fn = explicitFn;
+    }
+    else if (hasWildcards) {
+        throw new Error(`b3nd-save: URL contains wildcards but ?fn= is absent — declare ` +
+            `the verb explicitly (e.g. ?fn=find for "**", ?fn=ls for "*"/"?")`);
+    }
+    else {
+        fn = uriRaw.endsWith("/") ? "ls" : "read";
+    }
+    // Verb/shape validation when wildcards are present (§3.4).
+    if (hasWildcards) {
+        const hasDoubleStar = effectiveGlob.includes("**");
+        if (fn === "ls" && hasDoubleStar) {
+            throw new Error(`b3nd-save: ?fn=ls rejects URLs containing "**" — use ?fn=find for ` +
+                `recursive walks`);
+        }
+        if (fn === "find" && !hasDoubleStar) {
+            throw new Error(`b3nd-save: ?fn=find requires "**" in the URL (or in legacy ` +
+                `?pattern=); got "${effectiveGlob}"`);
+        }
+        // ?fn=count accepts both shapes per §3.2; x-* extensions are
+        // provider-defined and pass through; ?fn=read with wildcards is
+        // nonsense and we reject it explicitly so callers don't get a
+        // confusing point-read attempt on a literal "**" key.
+        if (fn === "read") {
+            throw new Error(`b3nd-save: ?fn=read rejects URLs containing wildcards — use ?fn=ls ` +
+                `or ?fn=find`);
+        }
+    }
+    return {
+        protocol,
+        hostname,
+        path,
+        program,
+        uri: effectiveUri,
+        glob: effectiveGlob,
+        fn,
+        params,
+        ext,
+    };
 }
 /**
  * Serialize a parsed url back to its string form. Authoritative input is
@@ -114,6 +298,12 @@ export function parseUrl(url) {
  *
  * Omits `fn=` when it matches the trailing-slash default. Throws if any
  * `ext` key does not start with `x-`.
+ *
+ * Note: `buildUrl` writes the URI verbatim — it does not splice a glob
+ * back into the path. Callers that have a `ParsedUrl` produced by
+ * `parseUrl` from a URI-embedded-glob source should reconstruct the
+ * full url manually if they need to round-trip the original string; the
+ * cheap path is `<originalUrl>` which they already have.
  */
 export function buildUrl(parsed) {
     const { uri, fn, params, ext } = parsed;
@@ -144,6 +334,10 @@ export function buildUrl(parsed) {
  * request-time-only and never participates in routing or storage
  * keying. Cheap helper for stores and callers that need the bare uri
  * without paying for full parse.
+ *
+ * Note: this returns the URI as written, **including** any embedded
+ * glob (`<uri-with-glob>`). For just the literal routing prefix, parse
+ * the url and read `parsed.uri`.
  */
 export function uriOf(url) {
     const qIdx = url.indexOf("?");

package/esm/walk-via-ls.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @module
+ * `walkViaLs` — caller-invoked polyfill that simulates `fn=find`
+ * against stores that advertise only `fn=ls`.
+ *
+ * **When to use.** A caller wants every entry under a prefix (the
+ * recursive-listing use case `fn=find` solves) but is targeting a store
+ * whose `status().fns` includes `"ls"` and NOT `"find"`. Without this
+ * helper the caller would have to hand-roll the recursive walk.
+ *
+ * **When NOT to use.** If the target store advertises `"find"`, call
+ * `?fn=find` directly — it will be cheaper (push-down where possible,
+ * single network round-trip in many cases). `walkViaLs` is the explicit
+ * fallback, *never* an auto-engaged dispatch fallback (per v1 spec §7
+ * `.cc-chat/20260625093437-listing-spec/output.md`). Capability check
+ * is the caller's responsibility:
+ *
+ * ```ts
+ * const status = await rig.status();
+ * const fns = status?.fns ?? [];
+ * const uris = fns.includes("find")
+ *   ? await rig.read([`${prefix}**?fn=find&format=uris`])
+ *   : await walkViaLs(rig.read.bind(rig), prefix, { format: "uris" });
+ * ```
+ *
+ * **Contract.** `walkViaLs` uses ONLY the standard b3nd PIN `read`
+ * surface — no privileged store access, no rig internals. It issues
+ * repeated shallow `?fn=ls&format=uris` calls level-by-level, recursing
+ * into each child whose own `?fn=ls&format=uris` returns at least one
+ * entry (probe-based directory detection — see Design notes below).
+ *
+ * **What this DOES NOT do:**
+ *   - No streaming. The full result accumulates before returning.
+ *   - No pagination. The helper always returns the complete walk; if
+ *     the underlying store's `ls` paginates, callers must wrap that
+ *     concern themselves (or push for `fn=find` support).
+ *   - No parallelism. Each level is walked serially. This is a
+ *     polyfill; the right answer for performance is `fn=find`.
+ *   - No content-equivalence guarantees with `fn=find`. Push-down
+ *     `fn=find` may sort/paginate differently. `walkViaLs` returns a
+ *     stable depth-first traversal in the order each level's `ls`
+ *     yields its children.
+ *
+ * **Cost model.** O(D) sequential round-trips where D is the count of
+ * non-empty directories under `prefix`. For deep trees this is much
+ * worse than a single `fn=find` push-down. Use only when capability
+ * forces it.
+ *
+ * **Design notes** (decisions documented for reviewers):
+ *
+ * 1. *Directory detection: probe via ls, not URI shape.* A naive
+ *    "no trailing slash → leaf" or "no dot-extension → directory"
+ *    heuristic would mis-classify common shapes (an entity named
+ *    `notes` with no extension; a file URI ending in `/`). Probing
+ *    via `?fn=ls&format=uris` is authoritative: if it returns any
+ *    URIs, recurse; if it returns the empty set, treat as terminal.
+ *    The cost is one extra ls per leaf URI — accepted because
+ *    `walkViaLs` is already O(D) and the spec calls it out as a slow
+ *    polyfill.
+ *
+ * 2. *Pattern filtering happens at the helper, not the wire.* The
+ *    underlying store's `ls` only supports `*` / `?` (no `**` — that's
+ *    why we're walking via ls). `compileSaveGlob` from `./glob.ts`
+ *    applies the full v2 §3.3 grammar (including `**`) to the
+ *    accumulated tail-URIs before returning. Callers see the same
+ *    glob semantics they would from `fn=find`.
+ *
+ * 3. *No cursor pagination.* `fn=find` ships a trailing cursor slot
+ *    (v2 §3.5); this polyfill always returns the full accumulated set
+ *    and never appends a cursor slot. Callers needing pagination must
+ *    upgrade to `fn=find`-capable storage.
+ */
+import type { Output } from "./deps/jsr.io/@bandeira-tech/b3nd-core/0.25.0/src/types/types.js";
+/**
+ * Options for {@link walkViaLs}. Mirrors the subset of `find` params
+ * the helper can honor against a `ls`-only store.
+ */
+export interface WalkViaLsOptions {
+    /**
+     * Glob pattern applied to URI tails (relative to `prefix`). Uses the
+     * v2 §3.3 grammar — `*`, `?`, and `**` all work. Patterns are matched
+     * against the post-prefix tail (same anchoring as `matchesGlob`).
+     * Defaults to "all descendants" (no pattern filter).
+     */
+    pattern?: string;
+    /**
+     * `"full"` (default) returns `Output[]` — each `[uri, payload]` is
+     * the result of a separate `?fn=read` on that leaf. `"uris"` returns
+     * `string[]` — leaf URIs only, no payload reads.
+     */
+    format?: "full" | "uris";
+    /**
+     * Soft cap on the number of distinct directories the helper will
+     * probe. Defaults to 10_000. When exceeded, the helper throws — the
+     * caller is almost certainly walking a larger tree than they meant
+     * to (or hitting a backend cycle). Set explicitly to opt into deeper
+     * walks.
+     */
+    maxDirs?: number;
+}
+/**
+ * Caller-invoked recursive `ls` walker — the polyfill for stores that
+ * advertise only `fn=ls`.
+ *
+ * @param read   The b3nd `read` surface (`rig.read`, a connection's
+ *               `read`, or any function with the same signature). Every
+ *               call passes a single-element URL array; the helper never
+ *               batches.
+ * @param prefix The routing prefix to walk. Trailing `/` is normalized
+ *               in — callers can pass either form.
+ * @param opts   See {@link WalkViaLsOptions}.
+ *
+ * @returns `Output[]` for `format=full` (default) or `string[]` for
+ *          `format=uris`. The ordering is depth-first, in the order each
+ *          probed directory's `ls` yields its children.
+ *
+ * @throws If a probed directory's `ls` rejects, the rejection
+ *         propagates. If the per-walk directory cap is exceeded, throws
+ *         `Error("walkViaLs: maxDirs exceeded")`.
+ */
+export declare function walkViaLs(read: <T = unknown>(urls: string[]) => Promise<Output<T>[]>, prefix: string, opts?: WalkViaLsOptions): Promise<Output[] | string[]>;
+//# sourceMappingURL=walk-via-ls.d.ts.map

package/esm/walk-via-ls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"walk-via-ls.d.ts","sourceRoot":"","sources":["../src/walk-via-ls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kEAAkE,CAAC;AAG/F;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAC3D,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,gBAAqB,GAC1B,OAAO,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CA+E9B"}