@plurnk/plurnk-service 4.1.0 → 4.3.0

package/dist/schemes/_entry-find.js

@@ -55,6 +55,7 @@ const uniqueMatchLocations = (locations) => {
 // label describes the same visible-body cost shown in the packet, a region reads in the one scope
 // notation ({§packet-extent-metadata}), and a location names its channel only off the default.
 const scoped = (key, value) => key === "region" || key === "enclosingRegion"
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- an item's region fields hold the TextRegions this module built; an entries walk does not carry which key holds which type
     ? ScopeFormat.region(value)
     : value;
 const renderFindContent = (items, defaultChannel) => renderJsonResult(items.map((item) => Array.isArray(item)
@@ -130,7 +131,7 @@ export const projectFindResult = (statement, scope, resources, scopes = [], defa
     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 });
+        return Results.assert({ status: page.status, problem: page.problem, ...fields, ...(page.range === undefined ? {} : { range: page.range }) });
     }
     if (statement.matcher !== null && matchingPathCount === 0) {
         return {
@@ -142,7 +143,7 @@ export const projectFindResult = (statement, scope, resources, scopes = [], defa
     const results = page.items ?? [];
     const returnedItemsWeightTotal = locationMode
         ? itemsWeightTotal
-        : results.reduce((sum, item) => sum + findItemWeight(item), 0);
+        : results.reduce((sum, item) => sum + (Array.isArray(item) ? findItemWeight(item) : 0), 0);
     return {
         status: 200,
         content: renderFindContent(results, defaultChannel), // {§find-result-projection} {§json-result-rendering}
@@ -155,6 +156,18 @@ export const projectFindResult = (statement, scope, resources, scopes = [], defa
         ...(page.range === undefined ? {} : { range: page.range }),
     };
 };
+// {§relation-indexed-dialects} An indexed dialect over candidates the index does not yet cover.
+const incompleteIndex = (search, what) => ({
+    status: 503,
+    matches: [],
+    error: `The persistent search index covers ${search.indexed} of ${search.total} ${what}.`,
+    extensions: {
+        search,
+        stage: "search-index",
+        recovery: "Wait for search indexing to complete before repeating the search.",
+        retryable: true,
+    },
+});
 export default class EntryFind {
     static #targetPath(scheme, authority, pathname, fragment, projectRoot) {
         const path = EntryManifest.toPath(scheme, authority, pathname, projectRoot);
@@ -173,6 +186,10 @@ export default class EntryFind {
     // framework) 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.
+    //
+    // The steps run in the order their refusals are owed — the channel, the scope and its exact
+    // miss, the candidates, the universe beyond membership, the scope filter, the matcher — and each
+    // returns either the refusal or what the next step needs.
     static async #matchPathnames(statement, ctx, manifest, address) {
         if (statement.target === null) {
             return {
@@ -186,12 +203,57 @@ export default class EntryFind {
             };
         }
         const fragment = statement.target.fragment ?? null;
-        const channel = fragment;
+        const unaddressed = EntryFind.#checkChannel(fragment, manifest);
+        if (unaddressed !== null)
+            return unaddressed;
+        const found = await EntryFind.#resolveScope(statement, ctx, manifest, address, fragment);
+        if ("status" in found)
+            return found;
+        const { scheme, authority, multipleAuthorities, scopePathname, scope } = found;
+        const superset = await EntryFind.#selectCandidates(statement, ctx, address, fragment, found);
+        if ("status" in superset)
+            return superset;
+        const coordinateByKey = new Map(superset.map((candidate) => [
+            multipleAuthorities ? EntryManifest.toPath(scheme, candidate.authority, candidate.pathname) : candidate.pathname,
+            { authority: candidate.authority, pathname: candidate.pathname },
+        ]));
+        const ambientKeys = await EntryFind.#ambientKeys(statement, address, found, superset);
+        const folders = EntryFind.#folderSummaries(statement, address, found, coordinateByKey, ambientKeys);
+        const inScope = EntryFind.#scopeCandidates(superset, found, address, fragment, ambientKeys);
+        if ("status" in inScope)
+            return inScope;
+        const candidates = multipleAuthorities
+            ? inScope.map((candidate) => ({ ...candidate, pathname: EntryManifest.toPath(scheme, candidate.authority, candidate.pathname) }))
+            : inScope;
+        const channels = new Map(candidates.map((candidate) => [candidate.pathname, candidate.channel]));
+        const channelOf = (key) => {
+            const selected = channels.get(key);
+            if (selected === undefined)
+                throw new Error(`FIND candidate lost its selected channel: ${key}`);
+            return selected;
+        };
+        const effectiveBytes = address.bytes === undefined ? undefined : (key) => {
+            const coordinate = coordinateByKey.get(key);
+            if (coordinate === undefined)
+                throw new Error(`FIND byte source lost coordinate ${key}`);
+            return address.bytes(coordinate.pathname, coordinate.authority);
+        };
+        const matches = await EntryFind.#selectMatches(statement, ctx, address, { candidates, ambientKeys, channelOf, effectiveBytes });
+        if ("status" in matches)
+            return matches;
+        const projectedScope = multipleAuthorities && scopePathname !== null
+            ? pathScope(EntryManifest.toPath(scheme, authority, scopePathname), manifest.folderScopes === true)
+            : scope;
+        return { status: 200, matches, channel: fragment ?? candidates[0]?.channel, ...(projectedScope === null ? {} : { scope: projectedScope }), folders,
+            ...(ambientKeys.length === 0 ? {} : { ambient: new Set(ambientKeys) }) };
+    }
+    // The channel the FIND addresses, refused when the scheme has no default or does not declare it.
+    static #checkChannel(fragment, manifest) {
         const availableChannels = [...new Set([
                 manifest.defaultChannel,
                 ...Object.keys(manifest.channels),
             ])].filter((candidate) => candidate.length > 0);
-        if (manifest.defaultChannel.length === 0 && Object.keys(manifest.channels).length > 0 && channel === null) {
+        if (manifest.defaultChannel.length === 0 && Object.keys(manifest.channels).length > 0 && fragment === null) {
             return {
                 status: 400,
                 matches: [],
@@ -227,6 +289,11 @@ export default class EntryFind {
                 },
             };
         }
+        return null;
+    }
+    // The scheme, authority and path scope the target names; an exact path that names nothing is the
+    // scheme's miss ({§fs-errno}) unless the universe beyond membership holds it ({§membership-auto-add}).
+    static async #resolveScope(statement, ctx, manifest, address, fragment) {
         // 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);
@@ -248,7 +315,10 @@ export default class EntryFind {
                 workspace_id: ctx.workspaceId,
                 scheme, authority, pathname: scope.pathname,
             });
-            if (exact === undefined) {
+            // {§membership-auto-add} — an exact miss on a candidate is a listing or a match, not a 404.
+            const ambientExact = exact === undefined && address.ambient !== undefined && scheme === "file"
+                && !scope.pathname.startsWith("../") && (await address.ambient.candidates(scope.pathname)).includes(scope.pathname);
+            if (exact === undefined && !ambientExact) {
                 const target = EntryFind.#targetPath(scheme, authority, scope.pathname, fragment, projectRoot);
                 return {
                     status: 404,
@@ -259,6 +329,13 @@ export default class EntryFind {
                 };
             }
         }
+        return { scheme, projectRoot, authority, multipleAuthorities, authorityScope, scopePathname, scope };
+    }
+    // {§find-scope-prefix-filter} {§find-scoped-isolation} The candidate rows: SQL's safe superset on the
+    // literal prefix, the authority glob applied, the asker's visibility applied, and derivation
+    // settled before an indexed dialect reads it.
+    static async #selectCandidates(statement, ctx, address, fragment, found) {
+        const { scheme, authority, multipleAuthorities, authorityScope, scope } = found;
         // SQL receives only the literal prefix and returns a safe superset. The
         // path matcher owns the shell-glob truth below: unlike SQLite GLOB, `*`
         // cannot cross `/`, while `**` can. A declared folder scope remains a
@@ -269,7 +346,7 @@ export default class EntryFind {
             workspace_id: workspaceId,
             scheme,
             authority: multipleAuthorities ? null : authority,
-            channel,
+            channel: fragment,
             scope_prefix: address.pathBase !== undefined && scope?.candidatePrefix?.startsWith("../")
                 ? null : scope?.candidatePrefix ?? null,
         });
@@ -283,21 +360,48 @@ export default class EntryFind {
         if (ctx.settleDerivations !== undefined && candidates.some((candidate) => candidate.deep_hash === null)) {
             return { status: 503, matches: [], error: "Resource metadata is still being derived.", extensions: { stage: "search-index" } };
         }
-        const coordinateByKey = new Map(candidates.map((candidate) => [
-            multipleAuthorities ? EntryManifest.toPath(scheme, candidate.authority, candidate.pathname) : candidate.pathname,
-            { authority: candidate.authority, pathname: candidate.pathname },
-        ]));
-        const folders = statement.matcher === null && scope !== null
-            ? [...Map.groupBy([...coordinateByKey.entries()], ([, coordinate]) => coordinate.authority)]
-                .flatMap(([authority, entries]) => pathFolderSummaries(scope, entries.map(([, coordinate]) => coordinate.pathname), address.pathBase)
+        return candidates;
+    }
+    // {§membership-auto-add} The universe beyond membership that joins the listing and the text match.
+    static async #ambientKeys(statement, address, found, candidates) {
+        const { scheme, multipleAuthorities, scope } = found;
+        // {§membership-auto-add} — the universe beyond membership joins the listing and the text match;
+        // the indexed dialects (`~`, `&`) see members only, since nothing unadmitted is indexed.
+        let ambientKeys = [];
+        if (address.ambient !== undefined && scheme === "file" && !multipleAuthorities
+            && !(statement.matcher !== null && (statement.matcher.dialect === "fts" || statement.matcher.dialect === "graph"))
+            && !(scope?.candidatePrefix?.startsWith("../") ?? false)) {
+            const known = new Set(candidates.map((candidate) => candidate.pathname));
+            try {
+                ambientKeys = (await address.ambient.candidates(scope?.candidatePrefix ?? null))
+                    .filter((key) => !known.has(key) && (scope === null || pathScopeMatches(scope, key, address.pathBase)));
+            }
+            catch {
+                ambientKeys = []; // a malformed glob is reported below, by the members' own filter
+            }
+        }
+        return ambientKeys;
+    }
+    // A listing's folder rows, grouped by authority when the target spans several.
+    static #folderSummaries(statement, address, found, coordinateByKey, ambientKeys) {
+        const { scheme, authority, multipleAuthorities, scope } = found;
+        return statement.matcher === null && scope !== null
+            ? [...Map.groupBy([...coordinateByKey.entries(), ...ambientKeys.map((key) => [key, { authority, pathname: key }])], ([, coordinate]) => coordinate.authority)]
+                .flatMap(([groupAuthority, entries]) => pathFolderSummaries(scope, entries.map(([, coordinate]) => coordinate.pathname), address.pathBase)
                 .map((folder) => ({
-                selector: multipleAuthorities ? EntryManifest.toPath(scheme, authority, folder.selector) : folder.selector,
-                pathnames: folder.pathnames.map((pathname) => multipleAuthorities ? EntryManifest.toPath(scheme, authority, pathname) : pathname),
+                selector: multipleAuthorities ? EntryManifest.toPath(scheme, groupAuthority, folder.selector) : folder.selector,
+                pathnames: folder.pathnames.map((pathname) => multipleAuthorities ? EntryManifest.toPath(scheme, groupAuthority, pathname) : pathname),
             })))
             : [];
+    }
+    // The shell-glob truth over the candidates ({§find-scope-prefix-filter}): a malformed glob is refused by
+    // name, and an exact path left with nothing is the scheme's miss.
+    static #scopeCandidates(candidates, found, address, fragment, ambientKeys) {
+        const { scheme, projectRoot, authority, multipleAuthorities, scopePathname, scope } = found;
+        let inScope = candidates;
         if (scope !== null) {
             try {
-                candidates = candidates.filter((c) => pathScopeMatches(scope, c.pathname, address.pathBase));
+                inScope = candidates.filter((c) => pathScopeMatches(scope, c.pathname, address.pathBase));
             }
             catch {
                 return {
@@ -312,7 +416,7 @@ export default class EntryFind {
                 };
             }
         }
-        if (!multipleAuthorities && scope?.kind === "exact" && candidates.length === 0) {
+        if (!multipleAuthorities && scope?.kind === "exact" && inScope.length === 0 && ambientKeys.length === 0) {
             const target = EntryFind.#targetPath(scheme, authority, scope.pathname, fragment, projectRoot);
             return {
                 status: 404,
@@ -322,49 +426,26 @@ export default class EntryFind {
                 extensions: missExtensions(scheme, target),
             };
         }
-        if (multipleAuthorities) {
-            candidates = candidates.map((candidate) => ({
-                ...candidate, pathname: EntryManifest.toPath(scheme, candidate.authority, candidate.pathname),
-            }));
-        }
-        const channels = new Map(candidates.map((candidate) => [candidate.pathname, candidate.channel]));
-        const channelOf = (key) => {
-            const selected = channels.get(key);
-            if (selected === undefined)
-                throw new Error(`FIND candidate lost its selected channel: ${key}`);
-            return selected;
-        };
-        const effectiveBytes = address.bytes === undefined ? undefined : (key) => {
-            const coordinate = coordinateByKey.get(key);
-            if (coordinate === undefined)
-                throw new Error(`FIND byte source lost coordinate ${key}`);
-            return address.bytes(coordinate.pathname, coordinate.authority);
-        };
-        // 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.
+        return inScope;
+    }
+    // Every dialect resolves to one selection per resource: rank for ~full-text, the relation index for
+    // &graph, every candidate for a bare listing, and the content matcher otherwise. Content dialects
+    // already carry honest match evidence; relation dialects map their indexed source spans into readable
+    // TextRegions.
+    static async #selectMatches(statement, ctx, address, selection) {
+        const { candidates, ambientKeys, channelOf } = selection;
         let matches;
         if (statement.matcher !== null && statement.matcher.dialect === "fts") {
             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: true,
-                    },
-                };
+                return incompleteIndex(candidateSet, "selected entries");
             const ranked = await EntryFts.rankCandidates(ctx.db, candidateSet.candidates, statement.matcher.raw.slice(1), ctx.signal);
             if (ranked.status !== 200)
                 return { status: ranked.status, matches: [], problem: ranked.problem };
             matches = ranked.matches.map(({ key, matches: locations }) => ({ pathname: key, matches: locations }));
         }
         else if (statement.matcher === null) {
-            matches = candidates.map((c) => ({ pathname: c.pathname, matches: [] }));
+            matches = [...candidates.map((c) => ({ pathname: c.pathname, matches: [] })), ...ambientKeys.map((pathname) => ({ pathname, matches: [] }))];
         }
         else if (statement.matcher.dialect === "graph") {
             // {§relation-indexed-dialects} Parser admission owns graph syntax;
@@ -385,33 +466,13 @@ export default class EntryFind {
             // in-scope candidates from the target glob for the final set.
             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: true,
-                    },
-                };
+                return incompleteIndex(scopedCandidates, "selected entries");
             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: true,
-                    },
-                };
+                return incompleteIndex(universe, "entries in the relationship universe");
             const graph = await EntryGraph.matchCandidates(ctx.db, universe.candidates, scopedCandidates.candidates, statement.matcher.raw);
             if (graph.status !== 200) {
                 return {
@@ -430,63 +491,99 @@ export default class EntryFind {
             }));
         }
         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
-            // one over log rows). Candidates key by pathname; each hit becomes a Match.
-            const textCandidates = [];
-            const byteCandidates = [];
-            // {§find-bytes}/{§binary-parity} — a binary channel is searched as bytes, never as its stored
-            // text form: from the scheme's byte supplier (a File member's disk) or, absent one, from the
-            // bytes a DB entry keeps base64 in its content. It is never handed to the text matcher, so its
-            // bytes cannot poison a text search; a binary channel with neither source has nothing to search.
-            const contentBytes = new Map();
-            for (const c of candidates) {
-                if (c.content === undefined || c.mimetype === undefined)
-                    throw new Error("EntryFind.#matchPathnames: content candidate is incomplete");
-                if (await MimetypeBinary.isBinaryMimetype(c.mimetype, mimetypes)) {
-                    if (effectiveBytes !== undefined)
-                        byteCandidates.push(c.pathname);
-                    else if (c.content !== "") {
-                        byteCandidates.push(c.pathname);
-                        contentBytes.set(c.pathname, EntryCrud.contentByteSource(c.content));
-                    }
+            const content = await EntryFind.#matchContent(statement.matcher, ctx, address, selection);
+            if ("status" in content)
+                return content;
+            matches = content;
+        }
+        return matches;
+    }
+    // {§find-source-agnostic} The content matcher over the candidates' text and bytes, and over the universe
+    // beyond membership: a hit there proposes admission instead of showing content ({§membership-auto-add}).
+    static async #matchContent(matcher, ctx, address, selection) {
+        const { candidates, ambientKeys, channelOf, effectiveBytes } = selection;
+        const { mimetypes } = ctx;
+        if (mimetypes === undefined)
+            throw new Error("EntryFind.#matchContent: body matcher requires the mimetypes capability in ctx");
+        // {§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 textCandidates = [];
+        const byteCandidates = [];
+        // {§find-bytes}/{§binary-parity} — a binary channel is searched as bytes, never as its stored
+        // text form: from the scheme's byte supplier (a File member's disk) or, absent one, from the
+        // bytes a DB entry keeps base64 in its content. It is never handed to the text matcher, so its
+        // bytes cannot poison a text search; a binary channel with neither source has nothing to search.
+        const contentBytes = new Map();
+        for (const c of candidates) {
+            if (c.content === undefined || c.mimetype === undefined)
+                throw new Error("EntryFind.#matchContent: content candidate is incomplete");
+            if (await MimetypeBinary.isBinaryMimetype(c.mimetype, mimetypes)) {
+                if (effectiveBytes !== undefined)
+                    byteCandidates.push(c.pathname);
+                else if (c.content !== "") {
+                    byteCandidates.push(c.pathname);
+                    contentBytes.set(c.pathname, EntryCrud.contentByteSource(c.content));
                 }
-                else
-                    textCandidates.push({ key: c.pathname, content: c.content, mimetype: c.mimetype });
             }
-            const byteSupplier = effectiveBytes ?? ((pathname) => contentBytes.get(pathname));
-            const r = textCandidates.length === 0
-                ? { status: 200, matches: [] }
-                : await Matcher.matchCandidates(statement.matcher, textCandidates, mimetypes);
-            if (r.status !== 200)
-                return {
-                    status: r.status,
-                    matches: [],
-                    problem: r.problem,
-                };
-            const bytesMatched = byteCandidates.length === 0
-                ? { status: 200, matches: [] }
-                : await EntryFind.#matchBytes(statement.matcher, byteCandidates, byteSupplier, mimetypes, channelOf);
-            if (bytesMatched.status !== 200)
-                return {
-                    status: bytesMatched.status,
-                    matches: [],
-                    problem: bytesMatched.problem,
-                };
-            matches = [
-                ...r.matches.map((match) => ({
-                    pathname: match.key,
-                    matches: match.matches.map((evidence) => ({ channel: channelOf(match.key), ...evidence })),
-                })),
-                ...bytesMatched.matches,
-            ];
+            else
+                textCandidates.push({ key: c.pathname, content: c.content, mimetype: c.mimetype });
         }
-        const projectedScope = multipleAuthorities && scopePathname !== null
-            ? pathScope(EntryManifest.toPath(scheme, authority, scopePathname), manifest.folderScopes === true)
-            : scope;
-        return { status: 200, matches, channel: fragment ?? candidates[0]?.channel, ...(projectedScope === null ? {} : { scope: projectedScope }), folders };
+        // {§membership-auto-add} — a candidate's text is matched from disk; a match admits it, and the
+        // selection runs again over members, so an unadmitted candidate never shows its content.
+        const ambientSet = new Set(ambientKeys);
+        for (const key of ambientKeys) {
+            const text = await address.ambient.text(key);
+            if (text?.content != null)
+                textCandidates.push({ key, content: text.content, mimetype: text.mimetype });
+        }
+        const byteSupplier = effectiveBytes ?? ((pathname) => contentBytes.get(pathname));
+        const r = textCandidates.length === 0
+            ? { status: 200, matches: [] }
+            : await Matcher.matchCandidates(matcher, textCandidates, mimetypes);
+        if (r.status !== 200)
+            return {
+                status: r.status,
+                matches: [],
+                problem: r.problem,
+            };
+        const ambientMatched = r.matches.filter((match) => ambientSet.has(match.key)).map((match) => match.key);
+        if (ambientMatched.length > 0) {
+            const proposal = await address.ambient.propose(ambientMatched);
+            if (proposal !== null)
+                return { status: 202, matches: [], proposal };
+        }
+        r.matches = r.matches.filter((match) => !ambientSet.has(match.key));
+        const bytesMatched = byteCandidates.length === 0
+            ? { status: 200, matches: [] }
+            : await EntryFind.#matchBytes(matcher, byteCandidates, byteSupplier, mimetypes, channelOf);
+        if (bytesMatched.status !== 200)
+            return {
+                status: bytesMatched.status,
+                matches: [],
+                problem: bytesMatched.problem,
+            };
+        return [
+            ...r.matches.map((match) => ({
+                pathname: match.key,
+                matches: match.matches.map((evidence) => ({ channel: channelOf(match.key), ...evidence })),
+            })),
+            ...bytesMatched.matches,
+        ];
+    }
+    // {§membership-auto-add} — a candidate's listing row: its type, weight and extent from disk, marked
+    // untracked; a binary or oversized candidate lists with no weight until a READ admits it.
+    static async #ambientItem(ambient, key, path, weigh) {
+        const text = await ambient.text(key);
+        if (text === null)
+            return null;
+        const content = text.content;
+        return [{
+                path,
+                mimetype: text.mimetype,
+                weight: content === null || weigh === undefined ? 0 : weigh(content),
+                lines: content === null ? 0 : content.split("\n").length,
+                aside: "untracked",
+            }];
     }
     // {§find-bytes} — the matcher runs over the bytes as one character each, so a text pattern
     // finds strings and `\xNN` escapes find byte sequences; every hit is re-expressed in byte
@@ -523,6 +620,9 @@ export default class EntryFind {
             match = await EntryFind.#matchPathnames(statement, ctx, manifest, address);
         }
         const empty = emptyFindFields();
+        // {§membership-auto-add} — the FIND proposes the admission of the candidates its pattern matched.
+        if (match.status === 202 && match.proposal !== undefined)
+            return { ...empty, ...match.proposal };
         if (match.status !== 200) {
             if (match.problem !== undefined) {
                 return Results.assert({
@@ -552,9 +652,16 @@ export default class EntryFind {
         const resources = [];
         for (const m of match.matches) {
             const row = byPath.get(addressOf(m.pathname));
-            if (row === undefined)
+            if (row !== undefined) {
+                resources.push({ item: row, match: m });
                 continue;
-            resources.push({ item: row, match: m });
+            }
+            // {§membership-auto-add} — a listed candidate has no catalog row; its row is read from disk.
+            if (match.ambient?.has(m.pathname) && address.ambient !== undefined) {
+                const item = await EntryFind.#ambientItem(address.ambient, m.pathname, addressOf(m.pathname), ctx.weigh);
+                if (item !== null)
+                    resources.push({ item, 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
@@ -567,8 +674,11 @@ export default class EntryFind {
                 let items = 0;
                 for (const pathname of folder.pathnames) {
                     const row = byPath.get(addressOf(pathname));
-                    if (row === undefined)
+                    if (row === undefined) {
+                        if (match.ambient?.has(pathname))
+                            items++;
                         continue;
+                    }
                     items++;
                     weight += row.reduce((sum, channel) => sum + channel.weight, 0);
                 }
@@ -580,7 +690,8 @@ export default class EntryFind {
         if (match.scope === undefined)
             throw new Error("FIND selection succeeded without a path scope");
         const projected = projectFindResult(statement, match.scope, resources, scopes, manifest.defaultChannel);
-        if (address.pathname === undefined)
+        // {§membership-auto-add} — a listed candidate has no stored representation to consume.
+        if (address.pathname === undefined || match.ambient?.has(address.pathname))
             return projected;
         // Exact FIND consumes the same selected canonical producer as exact
         // READ. Query projection remains core-owned, while the durable selected-