@plurnk/plurnk-service 1.3.12 → 1.5.0

package/dist/schemes/_entry-find.js

@@ -1,63 +1,133 @@
-// 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).
+// FIND helper for entry-bearing schemes (SPEC {§find}; plurnk.md FIND row).
+// FIND resolves one of two questions from the target shape. A broad target
+// returns catalog resources; an exact matcher target returns flat addressable
+// match locations. 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
 //             → the mimetypes plugin) and INCLUDES/EXCLUDES the entry — e.g.
 //             `FIND(log:///**/error):/timeout/i` keeps logs whose content matches.
 //   signal  — tag filter: candidate entry must have ALL listed tags
-//   <L>     — results pagination: select results N..M from the matched list
+//   <L>     — result pagination: resource or match-location positions N..M
+import { DEFAULT_RETRIEVAL_LIMIT, renderJsonResult } from "@plurnk/plurnk-contracts";
 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";
+export const findItemTokens = (item) => item.items === undefined
+    ? Object.values(item.channels).reduce((sum, channel) => sum + channel.tokens, 0)
+    : item.tokens;
+export const emptyFindFields = () => ({
+    content: null,
+    mimetype: null,
+    results: [],
+    itemsTokenTotal: 0,
+    returnedItemsTokenTotal: 0,
+    matchingPathCount: 0,
+    matchLocationCount: 0,
+});
+const uniqueMatchLocations = (locations) => {
+    const seen = new Set();
+    const unique = [];
+    for (const location of locations) {
+        const key = JSON.stringify(location);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(location);
+    }
+    return unique;
+};
+// {§find-result-projection} — selection remains grouped internally because
+// schemes and curation operate on resources. This one public projection owns
+// target-shape mode, pagination, counts, and rendering for every FIND source.
+export const projectFindResult = (statement, scope, resources, scopes = []) => {
+    const resourcePaths = new Set();
+    for (const { item } of resources) {
+        if (resourcePaths.has(item.path)) {
+            throw new Error(`FIND selection contains duplicate resource ${JSON.stringify(item.path)}`);
+        }
+        resourcePaths.add(item.path);
+    }
+    const matchingPathCount = resources.length;
+    const matchLocationCount = resources.reduce((sum, { match }) => sum + uniqueMatchLocations(match.matches).length, 0);
+    const itemsTokenTotal = resources.reduce((sum, { item }) => sum + findItemTokens(item), 0)
+        + scopes.reduce((sum, item) => sum + item.tokens, 0);
+    const fields = {
+        content: null,
+        mimetype: null,
+        results: [],
+        itemsTokenTotal,
+        returnedItemsTokenTotal: 0,
+        matchingPathCount,
+        matchLocationCount,
+    };
+    const locationMode = statement.body !== null && scope.kind === "exact";
+    const completeItems = locationMode
+        ? uniqueMatchLocations(resources.flatMap(({ match }) => match.matches))
+        : [
+            ...resources.map(({ item, match }) => statement.body === null
+                ? item
+                : { ...item, matchLocationCount: uniqueMatchLocations(match.matches).length }),
+            ...scopes,
+        ];
+    if (!locationMode && scopes.length > 0) {
+        completeItems.sort((a, b) => (a.path ?? "").localeCompare(b.path ?? ""));
+    }
+    const marker = statement.body?.dialect === "semantic"
+        ? EntrySemantic.resultSelection(statement.lineMarker).page
+        : statement.lineMarker ?? { marks: [1, DEFAULT_RETRIEVAL_LIMIT] };
+    const unit = locationMode ? "matchLocation" : "resource";
+    const page = LineMarkerOps.page(completeItems, marker, {
+        unit,
+        allowEmpty: statement.body !== null || statement.lineMarker === null,
+    });
+    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, ...fields, range: page.range });
+    }
+    if (statement.body !== null && matchingPathCount === 0) {
+        return {
+            status: 204,
+            ...fields,
+            ...(page.range === undefined ? {} : { range: page.range }),
+        };
+    }
+    const results = page.items ?? [];
+    const returnedItemsTokenTotal = locationMode
+        ? itemsTokenTotal
+        : results.reduce((sum, item) => sum + findItemTokens(item), 0);
+    return {
+        status: 200,
+        content: renderJsonResult(results), // {§find-result-projection} {§json-result-rendering}
+        mimetype: "application/json",
+        results,
+        itemsTokenTotal,
+        returnedItemsTokenTotal,
+        matchingPathCount,
+        matchLocationCount,
+        ...(page.range === undefined ? {} : { range: page.range }),
+    };
+};
 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();
@@ -69,105 +139,202 @@ export default class EntryFind {
             }
         return out;
     }
-    // Resolve a FIND to its matched workspace PATHNAMES — entry-level, unique, in result
+    // Resolve a FIND to its matched workspace resources — entry-level, unique, in result
     // 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
-    // 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: [] };
+    // 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). Match
+    // locations remain grouped by resource internally until the target-shaped public projection.
+    static async #matchPathnames(statement, ctx, manifest, address) {
+        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 scopePathname = address.pathname ?? EntryFind.#scopePathnameOf(statement);
+        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,
+                owner_id: address.ownerId ?? await Owner.commonsId(ctx.db, ctx.workspaceId),
+                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";
         let candidates = await db[semantic ? "find_workspace_entry_candidate_ids" : "find_workspace_entry_candidates"].all({
             workspace_id: workspaceId,
-            owner_id: explicitOwnerId ?? await Owner.commonsId(db, workspaceId),
+            owner_id: address.ownerId ?? 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,
+                    },
+                };
+            }
+            matches = await EntryFind.#addTextRegions(ranked.results.map((x) => ({
+                key: x.key,
+                span: { lineStart: x.lineStart, lineEnd: x.lineEnd },
+            })), ctx, manifest, address.ownerId);
         }
         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, address.ownerId);
         }
         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 +342,23 @@ 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 } : {}) }));
-        }
-        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: [] };
-            matches = page.items ?? [];
+                return {
+                    status: r.status,
+                    matches: [],
+                    problem: r.problem,
+                };
+            matches = r.matches.map((match) => ({ pathname: match.key, matches: match.matches }));
         }
-        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 +367,87 @@ 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
-    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);
+    // {mimetype, tokens, lines}, tags, stream lifecycle) — FIND is the filtered, navigable slice of
+    // that catalog, rendered as a JSON array (application/json). {§find-result-projection}
+    static async findWorkspaceEntries(statement, ctx, manifest, address = {}) {
+        const match = await EntryFind.#matchPathnames(statement, ctx, manifest, address);
+        const empty = emptyFindFields();
+        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.extensions);
+        }
         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 = [];
-        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) {
+        const byPath = new Map((await EntryManifest.catalogRowsFor(ctx, scheme, address.ownerId ?? await Owner.commonsId(ctx.db, ctx.workspaceId))).map((r) => [r.path, r]));
+        const resources = [];
+        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);
-            }
-            if (!seenPath.has(m.pathname)) {
-                seenPath.add(m.pathname);
-                itemsTokenTotal += Object.values(row.channels).reduce((s, c) => s + c.tokens, 0);
+            resources.push({ item: row, match: m });
+        }
+        // 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
+        // resource matches.
+        const scopes = [];
+        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) {
+                    scopes.push({ path: EntryManifest.toPath(scheme, folder.selector), items, tokens });
+                }
             }
         }
-        // §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).
-        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.`;
-            // 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 };
+        if (match.scope === undefined)
+            throw new Error("FIND selection succeeded without a path scope");
+        const projected = projectFindResult(statement, match.scope, resources, scopes);
+        if (address.pathname === undefined)
+            return projected;
+        // Exact FIND consumes the same selected canonical producer as exact
+        // READ. Query projection remains core-owned, while the durable default-
+        // channel outcome survives cold and warm acquisition identically.
+        const stored = await EntryCrud.readEntry(address.pathname, ctx, scheme, address.ownerId);
+        if (stored.status !== 200 || stored.entry === null) {
+            throw new Error(`EntryFind projected exact entry ${address.pathname} but could not read its canonical representation.`);
         }
-        // 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 };
+        const producerResult = stored.entry.channels[manifest.defaultChannel]?.producerResult;
+        return producerResult === undefined
+            ? projected
+            : Results.assert({
+                ...producerResult,
+                ...projected,
+                status: producerResult.status,
+            });
     }
 }
 //# sourceMappingURL=_entry-find.js.map