@plurnk/plurnk-service 1.3.12 → 1.4.0

package/dist/schemes/_entry-find.js

@@ -1,12 +1,11 @@
-// FIND helper for entry-bearing schemes (SPEC §find; plurnk.md FIND row).
+// FIND helper for entry-bearing schemes (SPEC {§find}; plurnk.md FIND row).
 // FIND resolves to the scheme's CATALOG ROWS — the very rows the manifest catalogs —
 // filtered to the statement's matches. A matcher (glob/regex/jsonpath/xpath/~semantic/
-// @graph) decides WHICH entries appear. A CONTENT matcher also stamps each row with
-// `matchLines` — the source line(s) where it hit (plurnk.md:31: FIND returns the matching
-// rows with the match lines in the metadata; the line CONTENT is a READ). The result is a
-// JSON array of catalog rows: the per-scheme slice of the catalog (§find-result-catalog-rows).
+// @graph) decides WHICH entries appear. Each selected entry appears once; its
+// optional `matches` metadata records every addressable source/readable range.
+// The content itself remains a READ.
 //
-// Slot semantics (plurnk.md §"Body matcher dispatch (FIND, READ, OPEN, FOLD)"):
+// FIND slot semantics (contracts SPEC §4/§7):
 //   target  — required scope (path or glob); selects which entries are candidates
 //   body    — matcher (glob/regex/jsonpath/xpath/~semantic/@graph). A content matcher
 //             runs against the entry's default-channel CONTENT (Matcher.matchAgainstContent
@@ -16,48 +15,28 @@
 //   <L>     — results pagination: select results N..M from the matched list
 import { LineMarkerOps } from "../content/index.js";
 import Matcher from "../content/matcher.js";
-import { decodePathParens } from "../core/path-decode.js";
+import { entryPathnameOf } from "../core/plurnk-uri.js";
 import EntryGraph from "./_entry-graph.js";
 import EntryCrud from "./_entry-crud.js";
 import EntryManifest from "./_entry-manifest.js";
 import Owner from "../core/Owner.js";
 import EntrySemantic from "./_entry-semantic.js";
+import Results from "../core/results.js";
+import { resolveSearchCandidates } from "./_search-candidate.js";
+import { pathFolderSummaries, pathScope, pathScopeMatches } from "./_path-scope.js";
+// FIND result ordinals are also packet line coordinates. Keep each top-level
+// item compact, adding only the boundary newline that makes row N addressable
+// as line N while retaining one valid JSON array. {§find-result-catalog-rows}
+export const renderFindContent = (results) => `[${results.map((result) => JSON.stringify(result)).join(",\n")}]`;
 export default class EntryFind {
     static #scopePathnameOf(statement) {
         const path = statement.target;
         if (path === null)
             return null;
-        if (path.kind === "regex")
-            return path.raw; // regex source — parens are syntax, never encoded
-        return decodePathParens(path.kind === "url" ? path.pathname : path.raw); // #239 item 4
-    }
-    static #paginate(items, marker) {
-        const total = items.length;
-        const { first, last } = marker;
-        // #209 — a fractional marker is a semantic similarity threshold; on a
-        // non-semantic (paginated) result it's nonsense → 416, never floored.
-        if (!Number.isInteger(first) || (last !== null && !Number.isInteger(last)))
-            return { status: 416 };
-        if (last === null) {
-            if (first === 0 || first === -1)
-                return { status: 200, items: [] };
-            if (first > 0 && first <= total)
-                return { status: 200, items: [items[first - 1]] };
-            return { status: 416 };
-        }
-        let n = first;
-        let m = last;
-        if (n === 0)
-            n = 1;
-        if (m === -1)
-            m = total;
-        if (n < 1 || n > total)
-            return { status: 416 };
-        if (m < 1 || m > total)
-            return { status: 416 };
-        if (n > m)
-            return { status: 416 };
-        return { status: 200, items: items.slice(n - 1, m) };
+        // FIND addresses the same canonical entry identity as READ and direct
+        // CRUD. Both namespace authorities and network hosts are part of that
+        // identity and must survive the exact-entry lookup.
+        return entryPathnameOf(path);
     }
     static #unique(xs) {
         const seen = new Set();
@@ -73,41 +52,50 @@ export default class EntryFind {
     // order (rank for ~semantic, candidate order otherwise). Candidate selection (scope +
     // tags) runs in SQL (find_workspace_entry_candidates); a content matcher then runs against
     // each candidate's default-channel CONTENT (Matcher.matchAgainstContent → the mimetypes
-    // plugin) and INCLUDES/EXCLUDES the entry — 200 keeps it, 204/415/203 drop it, 400
-    // (malformed matcher) fails the whole op. Path-scoping stays in the (target). Returns the
+    // plugin) and INCLUDES/EXCLUDES the entry - 200 keeps it, 204/203 drop it, and a
+    // 4xx matcher failure ends the whole operation. Path-scoping stays in the (target). Returns the
     // matched pathnames plus `locations` — each content hit's source line(s), keyed by pathname.
     static async #matchPathnames(statement, ctx, manifest, explicitOwnerId) {
-        if (statement.target === null)
-            return { status: 400, matches: [] };
+        if (statement.target === null) {
+            return {
+                status: 400,
+                matches: [],
+                error: "FIND requires a target.",
+                extensions: {
+                    recovery: "Provide the FIND target.",
+                    retryable: false,
+                },
+            };
+        }
         // Scope by the manifest's persisted entries.scheme (storedScheme; absent →
         // name). File persists under the reserved 'file' scheme ({§entry-identity-no-null}).
         const scheme = EntryCrud.identityScheme(manifest);
         const scopePathname = EntryFind.#scopePathnameOf(statement);
-        // {§fs-errno} — the green-lie pin (#545): a FIND whose target is an EXACT path (no glob,
-        // no folder scope) that resolves to NO entry is ENOENT with its fact — certifying empty
-        // over nothing taught run59's model that a real function did not exist. A glob/folder
-        // scope with zero matches stays the blessed orienting empty (§render-rule, owner: an
-        // empty survey says "don't look here").
-        if (statement.target.kind !== "regex" && scopePathname !== null && scopePathname.length > 0
-            && !scopePathname.includes("*") && !scopePathname.endsWith("/")) {
+        const scope = scopePathname === null
+            ? null
+            : pathScope(scopePathname, manifest.folderScopes === true);
+        // {§fs-errno} — an exact-path miss is ENOENT; an empty glob or folder
+        // survey is a successful empty result.
+        if (scope?.kind === "exact" && scope.pathname.length > 0) {
             const exact = await ctx.db.crud_find_workspace_entry.get({
                 workspace_id: ctx.workspaceId,
                 owner_id: explicitOwnerId ?? await Owner.commonsId(ctx.db, ctx.workspaceId),
-                scheme, pathname: scopePathname,
+                scheme, pathname: scope.pathname,
             });
-            if (exact === undefined)
-                return { status: 404, matches: [], error: `no entry at ${EntryManifest.toPath(scheme, scopePathname)}` };
+            if (exact === undefined) {
+                return {
+                    status: 404,
+                    matches: [],
+                    error: `No entry exists at ${EntryManifest.toPath(scheme, scope.pathname)}.`,
+                    extensions: { target: EntryManifest.toPath(scheme, scope.pathname) },
+                };
+            }
         }
-        // The target's GLOB scope. A FOLDER (trailing slash, incl. the scheme root `/`) expands to
-        // its contents — append `*`; a bare ENTRY path stays exact (one entry); an explicit glob
-        // passes through literally. The `*` is folderhood, not a blanket prefix — so FIND(README.md)
-        // is the one entry, uniform with READ's target contract (#286). grammar 0.46 regex-in-path:
-        // a `#pattern#flags` target filters by regex over the pathname (below), no scope glob.
-        // §find-scope-prefix-filter
-        const scopeGlob = statement.target.kind === "regex" || scopePathname === null || scopePathname.length === 0
-            ? null
-            : (scopePathname.endsWith("/") ? `${scopePathname}*` : scopePathname);
-        const tags = Array.isArray(statement.signal) ? statement.signal : []; // tag filter, AND semantics — §find-tag-filter-and-semantics
+        // SQL receives only the literal prefix and returns a safe superset. Node's
+        // path matcher owns the shell-glob truth below: unlike SQLite GLOB, `*`
+        // cannot cross `/`, while `**` can. A declared folder scope remains a
+        // recursive prefix independent of glob syntax. {§find-scope-prefix-filter}
+        const tags = Array.isArray(statement.signal) ? statement.signal : []; // tag filter, AND semantics — {§find-tag-filter-and-semantics}
         const tagsParam = tags.length > 0 ? JSON.stringify(tags) : "[]";
         const { db, workspaceId } = ctx;
         const semantic = statement.body?.dialect === "semantic";
@@ -116,58 +104,159 @@ export default class EntryFind {
             owner_id: explicitOwnerId ?? await Owner.commonsId(db, workspaceId),
             scheme,
             ...(semantic ? {} : { channel: manifest.defaultChannel }),
-            scope_pathname: scopeGlob,
+            scope_prefix: scope?.candidatePrefix ?? null,
             tags: tagsParam,
         });
-        // grammar 0.46 regex-in-path — a `#pattern#flags` target narrows candidates by regex
-        // over their pathname (in TS; SQLite has no regex). Malformed pattern → 400, parallel
-        // to a malformed body matcher.
-        if (statement.target.kind === "regex") {
-            let re;
+        const candidatePathnames = statement.body === null && scope?.kind === "glob" && scope.shallowPrefix !== null
+            ? candidates.map((candidate) => candidate.pathname)
+            : undefined;
+        if (scope !== null) {
             try {
-                re = new RegExp(statement.target.pattern, statement.target.flags || undefined);
+                candidates = candidates.filter((c) => pathScopeMatches(scope, c.pathname));
             }
             catch {
-                return { status: 400, matches: [] };
+                return {
+                    status: 400,
+                    matches: [],
+                    error: `The path glob '${scopePathname ?? ""}' is malformed.`,
+                    extensions: {
+                        target: scopePathname ?? "",
+                        recovery: "Correct the target glob.",
+                        retryable: false,
+                    },
+                };
             }
-            candidates = candidates.filter((c) => re.test(c.pathname));
         }
-        // Every dialect resolves to (file, span) items — one per match (#286). A body-less FIND
-        // selects the whole entry (span: null); a matcher selects spans within it.
+        // Every dialect resolves to one selection per resource. Content
+        // dialects already carry honest match evidence; relation dialects map
+        // their indexed source spans into readable TextRegions below.
         let matches;
         if (statement.body !== null && statement.body.dialect === "semantic") {
             // Semantic rank is exhaustive within the SAME target/tag candidate set as every
-            // other matcher. Passing entry identities into the ranker preserves top-K meaning:
+            // other matcher. Passing entry identities into the ranker preserves ranking meaning:
             // constrain first, then rank, never rank the corpus and discard out-of-scope hits.
             const { mimetypes } = ctx;
-            if (mimetypes === undefined)
-                return { status: 501, matches: [] };
-            const marker = statement.lineMarker === null
-                ? { first: EntrySemantic.defaultTopK(), last: null }
-                : LineMarkerOps.firstLast(statement.lineMarker);
-            const ranked = await EntrySemantic.rankSemantic(ctx.db, ctx.workspaceId, scheme, candidates.map(({ entry_id }) => entry_id), mimetypes, statement.body.raw, marker);
-            if (ranked.status !== 200)
-                return { status: ranked.status, matches: [] };
-            matches = ranked.results.map((x) => ({ pathname: x.pathname, span: { lineStart: x.lineStart, lineEnd: x.lineEnd } }));
+            if (mimetypes === undefined) {
+                return {
+                    status: 501,
+                    matches: [],
+                    error: "Semantic search requires the mimetypes capability.",
+                    extensions: {
+                        stage: "semantic-search",
+                        retryable: false,
+                    },
+                };
+            }
+            const selection = EntrySemantic.resultSelection(statement.lineMarker);
+            const candidateSet = resolveSearchCandidates(candidates.map(({ pathname, deep_hash }) => ({ key: pathname, deepHash: deep_hash })));
+            if (candidateSet.state === "incomplete")
+                return {
+                    status: 503,
+                    matches: [],
+                    error: `The persistent search index covers ${candidateSet.indexed} of ${candidateSet.total} selected entries.`,
+                    extensions: {
+                        search: candidateSet,
+                        stage: "search-index",
+                        recovery: "Wait for search indexing to complete before repeating the search.",
+                        retryable: false,
+                    },
+                };
+            const ranked = await EntrySemantic.rankCandidates(ctx.db, candidateSet.candidates, mimetypes, statement.body.raw, selection);
+            if (ranked.status !== 200) {
+                return {
+                    status: ranked.status,
+                    matches: [],
+                    error: ranked.status === 501
+                        ? "Similarity-threshold search requires an embedding provider."
+                        : "The requested similarity threshold is outside the supported range.",
+                    extensions: {
+                        stage: "semantic-search",
+                        ...(selection.threshold === null ? {} : { threshold: selection.threshold }),
+                        recovery: ranked.status === 501
+                            ? "Remove the decimal similarity threshold while embeddings are unavailable."
+                            : "Use a similarity threshold greater than zero and less than one.",
+                        retryable: false,
+                    },
+                };
+            }
+            let selected = ranked.results;
+            if (selection.page !== null) {
+                const page = LineMarkerOps.page(selected, selection.page);
+                if (page.status !== 200) {
+                    return {
+                        status: page.status,
+                        matches: [],
+                        problem: page.problem,
+                        range: page.range,
+                    };
+                }
+                selected = page.items ?? [];
+            }
+            matches = await EntryFind.#addTextRegions(selected.map((x) => ({
+                key: x.key,
+                span: { lineStart: x.lineStart, lineEnd: x.lineEnd },
+            })), ctx, manifest, explicitOwnerId);
         }
         else if (statement.body === null) {
-            matches = candidates.map((c) => ({ pathname: c.pathname, span: null }));
+            matches = candidates.map((c) => ({ pathname: c.pathname, matches: [] }));
         }
         else if (statement.body.dialect === "graph") {
-            // @graph (plurnk-service#186): body is `@<sym` / `@>sym` / `@sym`. EntryGraph resolves
+            // {§relation-indexed-dialects} Body is `@<sym` / `@>sym` / `@sym`. EntryGraph resolves
             // the relation across (workspace, scheme), each as a (file, span); intersect with the
             // in-scope candidates (target glob + tags) for the final set.
-            const inScope = new Set(candidates.map((c) => c.pathname));
-            const graph = await EntryGraph.match(ctx.db, ctx.workspaceId, scheme, statement.body.raw);
-            if (graph.status !== 200)
-                return { status: graph.status, matches: [] };
-            matches = graph.matches.filter((m) => inScope.has(m.pathname)).map((m) => ({ pathname: m.pathname, span: { lineStart: m.lineStart, lineEnd: m.lineEnd } }));
+            const scopedCandidates = resolveSearchCandidates(candidates.map(({ pathname, deep_hash }) => ({ key: pathname, deepHash: deep_hash })));
+            if (scopedCandidates.state === "incomplete")
+                return {
+                    status: 503,
+                    matches: [],
+                    error: `The persistent search index covers ${scopedCandidates.indexed} of ${scopedCandidates.total} selected entries.`,
+                    extensions: {
+                        search: scopedCandidates,
+                        stage: "search-index",
+                        recovery: "Wait for search indexing to complete before repeating the search.",
+                        retryable: false,
+                    },
+                };
+            const universeRows = await ctx.db.find_workspace_derivation_candidates.all({
+                workspace_id: ctx.workspaceId,
+            });
+            const universe = resolveSearchCandidates(universeRows.map(({ key, deep_hash }) => ({ key, deepHash: deep_hash })));
+            if (universe.state === "incomplete")
+                return {
+                    status: 503,
+                    matches: [],
+                    error: `The persistent search index covers ${universe.indexed} of ${universe.total} entries in the relationship universe.`,
+                    extensions: {
+                        search: universe,
+                        stage: "search-index",
+                        recovery: "Wait for search indexing to complete before repeating the search.",
+                        retryable: false,
+                    },
+                };
+            const graph = await EntryGraph.matchCandidates(ctx.db, universe.candidates, scopedCandidates.candidates, statement.body.raw);
+            if (graph.status !== 200) {
+                return {
+                    status: graph.status,
+                    matches: [],
+                    error: `The graph matcher '${statement.body.raw}' is malformed.`,
+                    extensions: {
+                        stage: "matcher",
+                        dialect: "graph",
+                        recovery: "Correct or remove the matcher.",
+                        retryable: false,
+                    },
+                };
+            }
+            matches = await EntryFind.#addTextRegions(graph.matches.map((m) => ({
+                key: m.key,
+                span: { lineStart: m.lineStart, lineEnd: m.lineEnd },
+            })), ctx, manifest, explicitOwnerId);
         }
         else {
             const { mimetypes } = ctx;
             if (mimetypes === undefined)
                 throw new Error("EntryFind.#matchPathnames: body matcher requires the mimetypes capability in ctx");
-            // §find-source-agnostic — the shared content-matcher primitive (Log.find runs the same
+            // {§find-source-agnostic} — the shared content-matcher primitive (Log.find runs the same
             // one over log rows). Candidates key by pathname; each hit becomes a Match.
             const r = await Matcher.matchCandidates(statement.body, candidates.map((c) => {
                 if (c.content === undefined || c.mimetype === undefined)
@@ -175,35 +264,57 @@ export default class EntryFind {
                 return { key: c.pathname, content: c.content, mimetype: c.mimetype };
             }), mimetypes);
             if (r.status !== 200)
-                return { status: r.status, matches: [] };
-            matches = r.matches.map((m) => ({ pathname: m.key, span: m.span, ...(m.path !== undefined ? { path: m.path } : {}) }));
+                return {
+                    status: r.status,
+                    matches: [],
+                    problem: r.problem,
+                };
+            matches = r.matches.map((match) => ({ pathname: match.key, matches: match.matches }));
         }
-        if (statement.lineMarker !== null && statement.body?.dialect !== "semantic") {
-            const page = EntryFind.#paginate(matches, LineMarkerOps.firstLast(statement.lineMarker));
-            if (page.status !== 200)
-                return { status: page.status, matches: [] };
+        if (statement.lineMarker !== null && statement.body?.dialect !== "semantic" && candidatePathnames === undefined) {
+            const page = LineMarkerOps.page(matches, statement.lineMarker);
+            if (page.status !== 200) {
+                if (statement.body !== null && matches.length === 0) {
+                    const failure = Results.failure(`scheme:${manifest.name}`, "selection-range-unavailable", 416, `The ${statement.body.dialect} matcher selected 0 resources; <${statement.lineMarker.marks.join(",")}> cannot select from an empty result set.`, {
+                        matches: [],
+                        range: page.range,
+                    }, {
+                        stage: "selection",
+                        dialect: statement.body.dialect,
+                        matchedResources: 0,
+                        range: page.range,
+                        recovery: "Correct or remove the matcher before choosing a range.",
+                        retryable: false,
+                    });
+                    if (failure.problem === undefined) {
+                        throw new Error("FIND selection range failure has no Problem Details");
+                    }
+                    return {
+                        status: failure.status,
+                        matches: [],
+                        problem: failure.problem,
+                        range: page.range,
+                    };
+                }
+                return {
+                    status: page.status,
+                    matches: [],
+                    problem: page.problem,
+                    range: page.range,
+                };
+            }
             matches = page.items ?? [];
         }
-        return { status: 200, matches };
+        return { status: 200, matches, ...(scope === null ? {} : { scope }), ...(candidatePathnames === undefined ? {} : { candidatePathnames }) };
     }
-    static async #addReadableRows(matches, ctx, manifest, explicitOwnerId) {
-        if (matches.every(({ span }) => span === null))
-            return matches.map((match) => ({ ...match, span: null }));
-        if (ctx.mimetypes === undefined)
-            throw new Error("EntryFind.#addReadableRows: matched entries require the mimetypes capability");
+    static async #addTextRegions(matches, ctx, manifest, explicitOwnerId) {
+        if (matches.every(({ span }) => span === null)) {
+            return [...new Set(matches.map(({ key }) => key))].map((pathname) => ({ pathname, matches: [] }));
+        }
         const scheme = EntryCrud.identityScheme(manifest);
         const ownerId = explicitOwnerId ?? await Owner.commonsId(ctx.db, ctx.workspaceId);
-        const grouped = new Map();
-        for (let index = 0; index < matches.length; index += 1) {
-            const match = matches[index];
-            if (match.span === null)
-                continue;
-            const indices = grouped.get(match.pathname) ?? [];
-            indices.push(index);
-            grouped.set(match.pathname, indices);
-        }
-        const resolved = matches.map((match) => ({ ...match, span: null }));
-        for (const [pathname, indices] of grouped) {
+        const candidates = [];
+        for (const pathname of new Set(matches.filter(({ span }) => span !== null).map(({ key }) => key))) {
             const row = await ctx.db.ops_read_channel.get({
                 workspace_id: ctx.workspaceId,
                 owner_id: ownerId,
@@ -212,89 +323,143 @@ export default class EntryFind {
                 channel: manifest.defaultChannel,
             });
             if (row === undefined)
-                throw new Error(`EntryFind.#addReadableRows: matched entry ${pathname} has no default channel`);
-            const rows = await ctx.mimetypes.rowsForLines({ content: row.content, hint: row.mimetype }, indices.map((index) => ({
-                line: matches[index].span.lineStart,
-                endLine: matches[index].span.lineEnd,
-            })));
-            if (rows.length !== indices.length)
-                throw new Error(`EntryFind.#addReadableRows: ${pathname} returned ${rows.length} rows for ${indices.length} spans`);
-            for (let offset = 0; offset < indices.length; offset += 1) {
-                const index = indices[offset];
-                const match = matches[index];
-                const readable = rows[offset];
-                resolved[index] = {
-                    ...match,
-                    span: {
-                        ...match.span,
-                        rowStart: readable.row,
-                        rowEnd: readable.endRow,
-                    },
-                };
-            }
+                throw new Error(`EntryFind.#addTextRegions: matched entry ${pathname} has no default channel`);
+            candidates.push({ key: pathname, ...row });
         }
-        return resolved;
+        const resolved = Matcher.addTextRegions(matches, candidates);
+        return resolved.map(({ key, matches: ranges }) => ({ pathname: key, matches: ranges }));
     }
     // FIND result = the scheme's catalog rows, filtered to the matched entries and kept in
     // match order. A catalog row is exactly what the manifest catalogs (path + per-channel
-    // {mimetype, tokens, lines}, tags, seconds) — FIND is the filtered, navigable slice of
-    // that catalog, rendered as a JSON array (application/json). §find-result-catalog-rows
+    // {mimetype, tokens, lines}, tags, stream lifecycle) — FIND is the filtered, navigable slice of
+    // that catalog, rendered as a JSON array (application/json). {§find-result-catalog-rows}
     static async findWorkspaceEntries(statement, ctx, manifest, explicitOwnerId) {
         const match = await EntryFind.#matchPathnames(statement, ctx, manifest, explicitOwnerId);
-        if (match.status !== 200)
-            return { status: match.status, content: null, mimetype: null, results: [], itemsTokenTotal: 0, pathnames: [], matches: [], ...(match.error !== undefined ? { error: match.error } : {}) }; // {§fs-errno} — the ENOENT fact rides through
-        const readableMatches = await EntryFind.#addReadableRows(match.matches, ctx, manifest, explicitOwnerId);
+        const empty = { content: null, mimetype: null, results: [], itemsTokenTotal: 0, pathnames: [], matches: [] };
+        if (match.status !== 200) {
+            if (match.problem !== undefined) {
+                return Results.assert({
+                    status: match.status,
+                    problem: match.problem,
+                    ...empty,
+                });
+            }
+            if (match.error === undefined) {
+                throw new Error(`EntryFind selection failed with status ${match.status} without Problem Details or a diagnostic.`);
+            }
+            return Results.failure(`scheme:${manifest.name}`, match.status === 404 ? "entry-not-found" : match.status === 416 ? "range-not-satisfiable" : "find-failed", match.status, match.error, empty, {
+                ...(match.range === undefined ? {} : { range: match.range }),
+                ...match.extensions,
+            });
+        }
+        // Internal matchers successfully return an empty candidate set. Public
+        // FIND owns its operation status: a matcher miss is 204, while a
+        // body-less empty catalog remains a successful survey. {§matcher-result-resource-selection}
+        if (statement.body !== null && match.matches.length === 0) {
+            return { status: 204, ...empty };
+        }
         const scheme = EntryCrud.identityScheme(manifest);
-        // The catalog row is keyed by its addressable path; align each match to its row through
-        // the same EntryManifest.toPath the catalog uses (single source of truth). Match order is
-        // preserved (rank for ~semantic); a match whose entry has no row (e.g. the self-excluded
-        // manifest) drops out. Each match becomes ONE result item carrying its span (#286).
+        // The catalog row is keyed by its addressable path; align each selected
+        // resource to its row through the same EntryManifest.toPath the catalog
+        // uses. Resource order is preserved (rank for ~semantic).
         // {§entry-owner} — the alignment draws from the SAME owner the candidates matched, so a
         // match never pairs with a coordinate-twin sibling's catalog metadata.
         const byPath = new Map((await EntryManifest.catalogRowsFor(ctx, scheme, explicitOwnerId ?? await Owner.commonsId(ctx.db, ctx.workspaceId))).map((r) => [r.path, r]));
-        const results = [];
+        let results = [];
         const matches = [];
-        const seenPath = new Set();
-        let itemsTokenTotal = 0; // content weight summed per UNIQUE entry (items repeat a file across its matches)
-        // Two granularities from one hit list (§matcher-selection-signal ÷ #286): `results` (the
-        // rx the model reads) keeps EVERY hit — on a single-line document the per-hit matchPath is
-        // the only thing distinguishing them; `matches` (the fan-out's delivery list) dedups by
-        // (pathname, span) — N hits on one source line deliver that line ONCE, no identical-row noise.
-        const seenSpan = new Set();
-        for (const m of readableMatches) {
+        let itemsTokenTotal = 0;
+        for (const m of match.matches) {
             const row = byPath.get(EntryManifest.toPath(scheme, m.pathname));
             if (row === undefined)
                 continue;
-            results.push(m.span !== null ? { ...row, matchSpan: m.span, ...(m.path !== undefined ? { matchPath: m.path } : {}) } : row);
-            const spanKey = `${m.pathname}\0${m.span === null ? "" : `${m.span.lineStart},${m.span.lineEnd}`}`;
-            if (!seenSpan.has(spanKey)) {
-                seenSpan.add(spanKey);
-                matches.push(m);
+            results.push(m.matches.length > 0 ? { ...row, matches: m.matches } : row);
+            matches.push(m);
+            itemsTokenTotal += Object.values(row.channels).reduce((sum, channel) => sum + channel.tokens, 0);
+        }
+        // A terminal single-star catalog is a one-level map. Keep real entries
+        // at that level and collapse deeper descendants into exact, actionable
+        // `dir/**` scopes. The summaries are navigation metadata, not hidden
+        // matches: READ(*) still fans out only over the direct real entries.
+        if (statement.body === null && match.scope !== undefined && match.candidatePathnames !== undefined) {
+            for (const folder of pathFolderSummaries(match.scope, match.candidatePathnames)) {
+                let tokens = 0;
+                let items = 0;
+                for (const pathname of folder.pathnames) {
+                    const row = byPath.get(EntryManifest.toPath(scheme, pathname));
+                    if (row === undefined)
+                        continue;
+                    items++;
+                    tokens += Object.values(row.channels).reduce((sum, channel) => sum + channel.tokens, 0);
+                }
+                if (items > 0) {
+                    results.push({ path: EntryManifest.toPath(scheme, folder.selector), items, tokens });
+                    itemsTokenTotal += tokens;
+                }
             }
-            if (!seenPath.has(m.pathname)) {
-                seenPath.add(m.pathname);
-                itemsTokenTotal += Object.values(row.channels).reduce((s, c) => s + c.tokens, 0);
+            results.sort((a, b) => a.path.localeCompare(b.path));
+            // `<L>` pages the catalog the model actually sees, folder summaries
+            // included. Only retained real-entry rows remain fan-out matches.
+            if (statement.lineMarker !== null) {
+                const page = LineMarkerOps.page(results, statement.lineMarker);
+                if (page.status !== 200) {
+                    if (page.problem === undefined) {
+                        throw new Error("FIND pagination failed without Problem Details");
+                    }
+                    return Results.assert({
+                        status: page.status,
+                        problem: page.problem,
+                        content: null,
+                        mimetype: null,
+                        results: [],
+                        itemsTokenTotal: 0,
+                        pathnames: [],
+                        matches: [],
+                    });
+                }
+                results = page.items ?? [];
+                const retained = new Set(results.filter((item) => item.items === undefined).map((item) => item.path));
+                for (let i = matches.length - 1; i >= 0; i--) {
+                    if (!retained.has(EntryManifest.toPath(scheme, matches[i].pathname)))
+                        matches.splice(i, 1);
+                }
+                itemsTokenTotal = results.reduce((sum, item) => sum + (item.items === undefined
+                    ? Object.values(item.channels).reduce((channelSum, channel) => channelSum + channel.tokens, 0)
+                    : item.tokens ?? 0), 0);
             }
         }
-        // §find-count-not-contents (#418) — a repo-scale FIND(**) over a 19k-entry workspace can't
-        // enumerate: materializing every match overflows the window (a clean grind should not be a
-        // crash-and-recover). Over the render budget, the result is a COUNT + narrow steer instead
-        // of the rows — the model sees "N match, too broad, narrow it" and adapts. INDEPENDENT of
-        // the window size: even a 256k window shouldn't render a whole repo's catalog into a turn.
-        // The meta line's count + itemsTokenTotal still self-describe the hit set. Budget is a knob
-        // (reader-declared); 0/unset = no gate (small workspaces enumerate as before).
+        // {§find-count-not-contents}: over the independent render limit, retain
+        // count and aggregate weight but never the enumerated rows. Zero disables.
         const budget = Number.parseInt(process.env.PLURNK_SERVICE_FIND_MAX_MATCHES ?? "0", 10);
         if (budget > 0 && results.length > budget) {
-            const steer = `${results.length} entries match, exceeding the render budget (${budget}) — not enumerated.`;
+            const noun = results.some((item) => item.items !== undefined) ? "catalog items" : "entries";
+            const steer = `${results.length} ${noun} match, exceeding the render budget (${budget}) — not enumerated.`;
             // Count-forward means COUNT ONLY. Retaining the enumerated arrays behind a
             // terse rendered steer defeated the contract twice: callers could still fan
             // every hidden match into work, and the full objects stayed resident. The
-            // overflow count + aggregate weight are the complete bounded result.
-            return { status: 200, content: steer, mimetype: "text/markdown", results: [], itemsTokenTotal, pathnames: [], matches: [], overflow: results.length };
+            // Omitted count + aggregate weight are the complete bounded result.
+            return {
+                status: 200,
+                content: steer,
+                mimetype: "text/markdown",
+                results: [],
+                itemsTokenTotal,
+                pathnames: [],
+                matches: [],
+                omittedItems: results.length,
+                maximumItems: budget,
+            };
         }
-        // Compact JSON — the model parses it natively; the `null, 2` pretty-print was ~36%
-        // whitespace of the catalog body, tokens the wire doesn't need.
-        return { status: 200, content: JSON.stringify(results), mimetype: "application/json", results, itemsTokenTotal, pathnames: [...seenPath], matches };
+        // Compact within rows; the single top-level boundary newline makes
+        // result ordinal N the universally numbered packet line N.
+        return {
+            status: 200,
+            content: renderFindContent(results),
+            mimetype: "application/json",
+            results,
+            itemsTokenTotal,
+            pathnames: matches.map(({ pathname }) => pathname),
+            matches,
+        };
     }
 }
 //# sourceMappingURL=_entry-find.js.map