@plurnk/plurnk-service 4.1.0 → 4.3.0

package/dist/schemes/Log.js

@@ -1,4 +1,4 @@
-import { PathSyntax, } from "@plurnk/plurnk-contracts";
+import { isRecord, PathSyntax, } from "@plurnk/plurnk-contracts";
 import Matcher from "../content/matcher.js";
 import { emptyFindFields, projectFindResult } from "./_entry-find.js";
 import { CoreSchemeAdapterBase } from "../core/CoreSchemeServices.js";
@@ -252,12 +252,15 @@ export default class Log extends CoreSchemeAdapterBase {
             mimetypeRx: row.mimetype_rx,
         });
         const trimmed = LogVisibility.parse(row.folded);
-        const { stream } = JSON.parse(row.attrs);
-        const result = row.mimetype_rx === "application/json" ? JSON.parse(row.rx) : {};
-        const media = (result.image ?? result.document ?? result.audio);
+        const attrs = JSON.parse(row.attrs);
+        const stream = isRecord(attrs) ? attrs.stream : undefined;
+        const parsed = row.mimetype_rx === "application/json" ? JSON.parse(row.rx) : {};
+        const result = isRecord(parsed) ? parsed : {};
+        const mediaValue = result.image ?? result.document ?? result.audio;
+        const media = isRecord(mediaValue) ? mediaValue : undefined;
         const attributes = {
             ...(typeof stream === "string" ? { stream } : {}),
-            ...(typeof result.nativeContentHash === "string" && media?.mimetype !== undefined
+            ...(typeof result.nativeContentHash === "string" && typeof media?.mimetype === "string"
                 ? { nativeContentHash: result.nativeContentHash, sourceProjection: { mimetype: media.mimetype, facts: media } }
                 : {}),
         };
@@ -297,18 +300,59 @@ export default class Log extends CoreSchemeAdapterBase {
         return this.#find(statement, core, false, null);
     }
     async #find(statement, core, allowTargetless = false, maxLogEntryId = null) {
-        const { db, workerId, mimetypes } = core;
-        const empty = (status, detail, extensions = {}) => {
-            const fields = emptyFindFields();
-            if (status >= 400 && detail === undefined) {
-                throw new Error(`Log.find: selection returned status ${status} without Problem Details or a diagnostic`);
-            }
-            return status >= 400
-                ? Results.failure("scheme:log", status === 404 ? "entry-not-found" : status === 416 ? "range-not-satisfiable" : status === 501 ? "matcher-not-implemented" : "find-failed", status, detail, fields, extensions)
-                : { status, ...fields };
-        };
+        const { db, workerId } = core;
+        const found = await this.#findScope(statement, core, allowTargetless, maxLogEntryId);
+        if ("status" in found)
+            return found;
+        const { scope, glob } = found;
+        const selected = await Log.#selectLogCandidates(db, workerId, scope, glob, maxLogEntryId);
+        if ("status" in selected)
+            return selected;
+        const { candidateRows, rows } = selected;
+        const candidateByCanonicalCoord = new Map(candidateRows.map((row) => [LogEntryProjection.base(row.coordinate), row]));
+        const projectedByCoordinate = new Map(candidateRows.map((r) => [r.coordinate, {
+                key: r.coordinate,
+                ...LogBody.readable({
+                    op: r.op,
+                    attrs: r.attrs,
+                    tx: r.tx,
+                    rx: r.rx,
+                    mimetypeTx: r.mimetype_tx,
+                    mimetypeRx: r.mimetype_rx,
+                }, LogVisibility.parse(r.folded)),
+            }]));
+        const projected = rows.map((row) => projectedByCoordinate.get(row.coordinate));
+        const weigh = core.weigh ?? contentWeight;
+        const settled = await Log.#settleIndexedCandidates(statement, core, rows, scope, maxLogEntryId);
+        const matches = await Log.#selectLogMatches(statement, core, settled, projected, maxLogEntryId);
+        if ("status" in matches)
+            return matches;
+        return Log.#projectLogFind(statement, scope, matches, { candidateRows, projectedByCoordinate, candidateByCanonicalCoord }, weigh);
+    }
+    // A FIND result with no items: the status alone, or the failure a status of 400 and above must explain.
+    static #emptyFind(status, detail, extensions = {}) {
+        const fields = emptyFindFields();
+        if (status >= 400 && detail === undefined) {
+            throw new Error(`Log.find: selection returned status ${status} without Problem Details or a diagnostic`);
+        }
+        return status >= 400
+            ? Results.failure("scheme:log", status === 404 ? "entry-not-found" : status === 416 ? "range-not-satisfiable" : status === 501 ? "matcher-not-implemented" : "find-failed", status, detail, fields, extensions)
+            : { status, ...fields };
+    }
+    // {§relation-indexed-dialects} An indexed dialect over rows the index does not yet cover.
+    static #incompleteIndex(search, what) {
+        return Log.#emptyFind(503, `The persistent search index covers ${search.indexed} of ${search.total} ${what}.`, {
+            search,
+            stage: "search-index",
+            recovery: "Wait for search indexing to complete before repeating the search.",
+            retryable: false,
+        });
+    }
+    // {§log-coordinate-hierarchy} The scope the target names: a coordinate, a prefix or a glob, refused when
+    // malformed; an exact coordinate that names no row is the miss with its near miss.
+    async #findScope(statement, core, allowTargetless, maxLogEntryId) {
         if (statement.target === null && !allowTargetless) {
-            return empty(400, "FIND requires a log target.", {
+            return Log.#emptyFind(400, "FIND requires a log target.", {
                 recovery: "Provide a log coordinate, prefix, or glob.",
                 retryable: false,
             });
@@ -318,7 +362,7 @@ export default class Log extends CoreSchemeAdapterBase {
             : (statement.target.kind === "url" ? statement.target.pathname : statement.target.raw).replace(/^\//, "");
         const glob = coordinateGlob(normalizeLogTarget(pathname));
         if (glob === null) {
-            return empty(400, `The log target '${pathname}' is malformed.`, {
+            return Log.#emptyFind(400, `The log target '${pathname}' is malformed.`, {
                 target: pathname,
                 recovery: LOG_TARGET_SHAPE,
                 retryable: false,
@@ -331,9 +375,14 @@ export default class Log extends CoreSchemeAdapterBase {
                 throw new Error(`Exact log scope has a malformed coordinate ${JSON.stringify(scope.pathname)}`);
             if (await this.#resolveExactId(coordinate, core, maxLogEntryId) === null) {
                 const recovery = await nearMissRecovery(coordinate, core, maxLogEntryId);
-                return empty(404, `No log entry exists at ${statement.target?.raw ?? `log:///${scope.pathname}`}.`, { target: statement.target?.raw ?? `log:///${scope.pathname}`, ...(recovery === undefined ? {} : { recovery }) });
+                return Log.#emptyFind(404, `No log entry exists at ${statement.target?.raw ?? `log:///${scope.pathname}`}.`, { target: statement.target?.raw ?? `log:///${scope.pathname}`, ...(recovery === undefined ? {} : { recovery }) });
             }
         }
+        return { scope, glob };
+    }
+    // The candidate rows under the scope: the coordinate-scoped superset, then the shell-glob truth over it,
+    // which refuses a malformed glob by name.
+    static async #selectLogCandidates(db, workerId, scope, glob, maxLogEntryId) {
         const storedCandidateRows = await db.log_find_candidates.all({
             worker_id: workerId,
             scope_prefix: coordinateCandidatePrefix(scope.candidatePrefix),
@@ -345,26 +394,18 @@ export default class Log extends CoreSchemeAdapterBase {
             rows = candidateRows.filter((row) => coordinateScopeMatches(scope, row.coordinate));
         }
         catch {
-            return empty(400, `The log glob '${glob}' is malformed.`, {
+            return Log.#emptyFind(400, `The log glob '${glob}' is malformed.`, {
                 target: glob,
                 recovery: "Correct the log glob.",
                 retryable: false,
             });
         }
-        const candidateByCanonicalCoord = new Map(candidateRows.map((row) => [LogEntryProjection.base(row.coordinate), row]));
-        const projectedByCoordinate = new Map(candidateRows.map((r) => [r.coordinate, {
-                key: r.coordinate,
-                ...LogBody.readable({
-                    op: r.op,
-                    attrs: r.attrs,
-                    tx: r.tx,
-                    rx: r.rx,
-                    mimetypeTx: r.mimetype_tx,
-                    mimetypeRx: r.mimetype_rx,
-                }, LogVisibility.parse(r.folded)),
-            }]));
-        const projected = rows.map((row) => projectedByCoordinate.get(row.coordinate));
-        const weigh = core.weigh ?? contentWeight;
+        return { candidateRows, rows };
+    }
+    // {§relation-indexed-dialects} The rows an indexed dialect reads, their derivation settled once when the
+    // pass has not covered them yet.
+    static async #settleIndexedCandidates(statement, core, rows, scope, maxLogEntryId) {
+        const { db, workerId } = core;
         // {§relation-indexed-dialects} — an index-backed dialect (~, &) holds the program until the pass
         // covers its candidates: settle once, then re-read the attachments it produced. The 503s
         // below remain the truth when coverage is still incomplete afterwards.
@@ -378,19 +419,20 @@ export default class Log extends CoreSchemeAdapterBase {
                     max_id: maxLogEntryId,
                 }));
                 const hashes = new Map(refreshed.map((row) => [row.coordinate, row.deep_hash]));
-                rows = rows.map((row) => ({ ...row, deep_hash: hashes.get(row.coordinate) ?? row.deep_hash }));
+                return rows.map((row) => ({ ...row, deep_hash: hashes.get(row.coordinate) ?? row.deep_hash }));
             }
         }
+        return rows;
+    }
+    // Every dialect resolves to one selection per row: rank for ~full-text, the relation index for &graph, every
+    // row for a bare listing, and the content matcher otherwise ({§find-source-agnostic}).
+    static async #selectLogMatches(statement, core, rows, projected, maxLogEntryId) {
+        const { db, workerId, mimetypes } = core;
         let matches;
         if (statement.matcher?.dialect === "fts") {
             const candidateSet = resolveSearchCandidates(rows.map(({ coordinate, deep_hash }) => ({ key: coordinate, deepHash: deep_hash })));
             if (candidateSet.state === "incomplete")
-                return empty(503, `The persistent search index covers ${candidateSet.indexed} of ${candidateSet.total} selected log results.`, {
-                    search: candidateSet,
-                    stage: "search-index",
-                    recovery: "Wait for search indexing to complete before repeating the search.",
-                    retryable: false,
-                });
+                return Log.#incompleteIndex(candidateSet, "selected log results");
             const ranked = await EntryFts.rankCandidates(db, candidateSet.candidates, statement.matcher.raw.slice(1), core.signal);
             if (ranked.status !== 200) {
                 return Results.assert({ status: ranked.status, problem: ranked.problem, ...emptyFindFields() });
@@ -400,12 +442,7 @@ export default class Log extends CoreSchemeAdapterBase {
         else if (statement.matcher?.dialect === "graph") {
             const candidateSet = resolveSearchCandidates(rows.map(({ coordinate, deep_hash }) => ({ key: coordinate, deepHash: deep_hash })));
             if (candidateSet.state === "incomplete")
-                return empty(503, `The persistent search index covers ${candidateSet.indexed} of ${candidateSet.total} selected log results.`, {
-                    search: candidateSet,
-                    stage: "search-index",
-                    recovery: "Wait for search indexing to complete before repeating the search.",
-                    retryable: false,
-                });
+                return Log.#incompleteIndex(candidateSet, "selected log results");
             const universeRows = projectedCoordinateRows(await db.log_find_candidates.all({
                 worker_id: workerId,
                 scope_prefix: null,
@@ -413,12 +450,7 @@ export default class Log extends CoreSchemeAdapterBase {
             }));
             const universe = resolveSearchCandidates(universeRows.map(({ coordinate, deep_hash }) => ({ key: coordinate, deepHash: deep_hash })));
             if (universe.state === "incomplete")
-                return empty(503, `The persistent search index covers ${universe.indexed} of ${universe.total} log results in the relationship universe.`, {
-                    search: universe,
-                    stage: "search-index",
-                    recovery: "Wait for search indexing to complete before repeating the search.",
-                    retryable: false,
-                });
+                return Log.#incompleteIndex(universe, "log results in the relationship universe");
             const graph = await EntryGraph.matchCandidates(db, universe.candidates, candidateSet.candidates, statement.matcher.raw);
             if (graph.status !== 200)
                 return { ...graph, ...emptyFindFields() };
@@ -429,7 +461,7 @@ export default class Log extends CoreSchemeAdapterBase {
         }
         else {
             if (mimetypes === undefined) {
-                return empty(501, "Content matching requires the mimetypes capability.", {
+                return Log.#emptyFind(501, "Content matching requires the mimetypes capability.", {
                     stage: "matcher",
                     dialect: statement.matcher.dialect,
                     retryable: false,
@@ -448,6 +480,12 @@ export default class Log extends CoreSchemeAdapterBase {
             }
             matches = r.matches.map(({ key, matches: ranges }) => ({ pathname: key, matches: ranges }));
         }
+        return matches;
+    }
+    // {§find-result-projection} The matches as catalog resources and the listing's folder scopes, weighed as the
+    // packet would weigh them.
+    static #projectLogFind(statement, scope, matches, selection, weigh) {
+        const { candidateRows, projectedByCoordinate, candidateByCanonicalCoord } = selection;
         const folderSummaries = statement.matcher === null
             ? pathFolderSummaries(scope, candidateRows.map((row) => LogEntryProjection.base(row.coordinate)))
             : [];
@@ -624,83 +662,6 @@ export default class Log extends CoreSchemeAdapterBase {
     // {§log-kill-scope} — a scoped KILL suppresses the selected lines from the
     // packet projection; the durable row keeps its canonical body.
     async #planScoped(statement, ctx, maxLogEntryId) {
-        const planned = async (ids, exact) => {
-            const rows = await ctx.db.log_curation_targets.all({ ids: JSON.stringify(ids), turn_id: ctx.turnId });
-            if (rows.length !== ids.length) {
-                throw new Error("Log curation selection changed before its visibility plan was resolved.");
-            }
-            const targets = [];
-            for (const row of rows) {
-                if (row.native_active === 1) {
-                    const folded = LogVisibility.parse(row.folded);
-                    targets.push({ id: row.id, activeBefore: 1, activeAfter: 0, foldedBefore: folded, foldedAfter: folded });
-                    continue;
-                }
-                const body = LogBody.resolve({
-                    op: row.op,
-                    attrs: row.attrs,
-                    tx: row.tx,
-                    rx: row.rx,
-                    mimetypeTx: row.mimetype_tx,
-                    mimetypeRx: row.mimetype_rx,
-                });
-                const identity = `log:///${LogEntryProjection.coordinate(row.coordinate, row)}`;
-                const result = row.mimetype_rx === "application/json"
-                    ? JSON.parse(row.rx)
-                    : null;
-                const rawAnchors = LogEntryProjection.op(row) === "READ"
-                    && result !== null
-                    && typeof result === "object"
-                    && Object.hasOwn(result, "lineAnchors")
-                    ? result.lineAnchors
-                    : [];
-                if (!Array.isArray(rawAnchors)) {
-                    throw new TypeError("A READ log body carries malformed published line anchors.");
-                }
-                const scope = LogVisibility.resolveScope(statement.lineMarker, identity, body.content, rawAnchors);
-                if (!scope.ok) {
-                    return {
-                        result: Results.failure("scheme:log", scope.code, scope.status, scope.detail, {}, {
-                            target: identity,
-                            recovery: scope.recovery,
-                            retryable: false,
-                        }),
-                        plan: null,
-                    };
-                }
-                const before = LogVisibility.parse(row.folded);
-                // {§emission-row}: source announcements are curated whole; ordinary rows own their bodies.
-                if (LogEntryProjection.isEmission(row)) {
-                    if (exact) {
-                        return {
-                            result: Results.failure("scheme:log", "emission-curated-whole", 422, `${identity} is an emission; curate it without a line scope.`, {}, {
-                                target: identity,
-                                recovery: `KILL (${identity}) retires it.`,
-                                retryable: false,
-                            }),
-                            plan: null,
-                        };
-                    }
-                    targets.push({ id: row.id, activeBefore: 1, activeAfter: 1, foldedBefore: before, foldedAfter: before });
-                    continue;
-                }
-                targets.push({
-                    id: row.id,
-                    activeBefore: 1,
-                    activeAfter: 1,
-                    foldedBefore: before,
-                    foldedAfter: LogVisibility.apply(before, scope.range, TextCoordinates.lineCount(body.content)),
-                });
-            }
-            return {
-                result: { status: 200, matched: ids.length },
-                plan: {
-                    targets,
-                    add: [],
-                    remove: [],
-                },
-            };
-        };
         if (statement.matcher !== null) {
             const matched = await this.#resolveByMatcher(statement, ctx, maxLogEntryId);
             if (matched.status === 204)
@@ -717,7 +678,7 @@ export default class Log extends CoreSchemeAdapterBase {
                     plan: null,
                 };
             }
-            return planned(matched.ids, false);
+            return Log.#scopedPlan(statement, ctx, matched.ids, false);
         }
         if (statement.target === null) {
             return {
@@ -732,24 +693,110 @@ export default class Log extends CoreSchemeAdapterBase {
         const selected = await this.#resolveIds(pathname, ctx, maxLogEntryId);
         if (selected.status === 204)
             return { result: { status: 204, matched: 0 }, plan: null };
-        if (selected.status !== 200) {
-            const exact = selected.status === 404 ? parseCoordinate(pathname) : null;
-            const nearMiss = exact === null ? undefined : await nearMissRecovery(exact, ctx, maxLogEntryId);
+        if (selected.status !== 200)
+            return Log.#selectionFailure(selected, pathname, ctx, maxLogEntryId, "curation-failed");
+        return Log.#scopedPlan(statement, ctx, selected.ids, parseCoordinate(pathname) !== null);
+    }
+    // {§log-kill-scope} The visibility plan for the selected rows: each row's own target, or the first row's refusal.
+    static async #scopedPlan(statement, ctx, ids, exact) {
+        const rows = await ctx.db.log_curation_targets.all({ ids: JSON.stringify(ids), turn_id: ctx.turnId });
+        if (rows.length !== ids.length) {
+            throw new Error("Log curation selection changed before its visibility plan was resolved.");
+        }
+        const targets = [];
+        for (const row of rows) {
+            const target = Log.#scopedRowTarget(statement, row, exact);
+            if ("plan" in target)
+                return target;
+            targets.push(target);
+        }
+        return {
+            result: { status: 200, matched: ids.length },
+            plan: {
+                targets,
+                add: [],
+                remove: [],
+            },
+        };
+    }
+    // One row under a scoped KILL: a natively active row retires whole; an emission is curated whole
+    // ({§emission-row}) and refused under an exact scope; any other row folds the resolved line range out of its
+    // visibility, or refuses with the scope's own Problem.
+    static #scopedRowTarget(statement, row, exact) {
+        if (row.native_active === 1) {
+            const folded = LogVisibility.parse(row.folded);
+            return { id: row.id, activeBefore: 1, activeAfter: 0, foldedBefore: folded, foldedAfter: folded };
+        }
+        const body = LogBody.resolve({
+            op: row.op,
+            attrs: row.attrs,
+            tx: row.tx,
+            rx: row.rx,
+            mimetypeTx: row.mimetype_tx,
+            mimetypeRx: row.mimetype_rx,
+        });
+        const identity = `log:///${LogEntryProjection.coordinate(row.coordinate, row)}`;
+        const result = row.mimetype_rx === "application/json"
+            ? JSON.parse(row.rx)
+            : null;
+        const rawAnchors = LogEntryProjection.op(row) === "READ" && isRecord(result) && Object.hasOwn(result, "lineAnchors")
+            ? result.lineAnchors
+            : [];
+        if (!Array.isArray(rawAnchors)) {
+            throw new TypeError("A READ log body carries malformed published line anchors.");
+        }
+        const scope = LogVisibility.resolveScope(statement.lineMarker, identity, body.content, rawAnchors);
+        if (!scope.ok) {
             return {
-                result: Results.failure("scheme:log", selected.status === 404 ? "entry-not-found" : "curation-failed", selected.status, selected.error ?? `No log entry matches '${pathname}'.`, {}, {
-                    target: pathname,
-                    ...(nearMiss === undefined ? {} : { recovery: nearMiss }),
-                    ...(selected.status === 400
-                        ? {
-                            recovery: LOG_TARGET_SHAPE,
-                            retryable: false,
-                        }
-                        : {}),
+                result: Results.failure("scheme:log", scope.code, scope.status, scope.detail, {}, {
+                    target: identity,
+                    recovery: scope.recovery,
+                    retryable: false,
                 }),
                 plan: null,
             };
         }
-        return planned(selected.ids, parseCoordinate(pathname) !== null);
+        const before = LogVisibility.parse(row.folded);
+        // {§emission-row}: source announcements are curated whole; ordinary rows own their bodies.
+        if (LogEntryProjection.isEmission(row)) {
+            if (exact) {
+                return {
+                    result: Results.failure("scheme:log", "emission-curated-whole", 422, `${identity} is an emission; curate it without a line scope.`, {}, {
+                        target: identity,
+                        recovery: `KILL (${identity}) retires it.`,
+                        retryable: false,
+                    }),
+                    plan: null,
+                };
+            }
+            return { id: row.id, activeBefore: 1, activeAfter: 1, foldedBefore: before, foldedAfter: before };
+        }
+        return {
+            id: row.id,
+            activeBefore: 1,
+            activeAfter: 1,
+            foldedBefore: before,
+            foldedAfter: LogVisibility.apply(before, scope.range, TextCoordinates.lineCount(body.content)),
+        };
+    }
+    // {§log-target-tolerances} A selection that found nothing or could not be read, named as what it was: an exact
+    // coordinate's miss carries its near miss, a malformed target the working form.
+    static async #selectionFailure(selected, pathname, ctx, maxLogEntryId, code) {
+        const exact = selected.status === 404 ? parseCoordinate(pathname) : null;
+        const nearMiss = exact === null ? undefined : await nearMissRecovery(exact, ctx, maxLogEntryId);
+        return {
+            result: Results.failure("scheme:log", selected.status === 404 ? "entry-not-found" : code, selected.status, selected.error ?? `No log entry matches '${pathname}'.`, {}, {
+                target: pathname,
+                ...(nearMiss === undefined ? {} : { recovery: nearMiss }),
+                ...(selected.status === 400
+                    ? {
+                        recovery: LOG_TARGET_SHAPE,
+                        retryable: false,
+                    }
+                    : {}),
+            }),
+            plan: null,
+        };
     }
     // {§log-curation-set-selection} — the target and an optional pattern select the rows by
     // intersection, exactly as they do for a scoped KILL; a scope only decides what happens to them.
@@ -762,23 +809,8 @@ export default class Log extends CoreSchemeAdapterBase {
         if (selected.problem !== undefined) {
             return { result: Results.assert({ status: selected.status, problem: selected.problem }), plan: null };
         }
-        if (selected.status !== 200) {
-            const exact = selected.status === 404 ? parseCoordinate(pathname) : null;
-            const nearMiss = exact === null ? undefined : await nearMissRecovery(exact, ctx, maxLogEntryId);
-            return {
-                result: Results.failure("scheme:log", selected.status === 404 ? "entry-not-found" : "kill-failed", selected.status, selected.error ?? `No log entry matches '${pathname}'.`, {}, {
-                    target: pathname,
-                    ...(nearMiss === undefined ? {} : { recovery: nearMiss }),
-                    ...(selected.status === 400
-                        ? {
-                            recovery: LOG_TARGET_SHAPE,
-                            retryable: false,
-                        }
-                        : {}),
-                }),
-                plan: null,
-            };
-        }
+        if (selected.status !== 200)
+            return Log.#selectionFailure(selected, pathname, ctx, maxLogEntryId, "kill-failed");
         const rows = await ctx.db.log_curation_targets.all({
             ids: JSON.stringify(selected.ids),
             turn_id: ctx.turnId,