@graview/core 0.1.0

package/dist/search.d.ts

@@ -0,0 +1,215 @@
+import { type Condition } from "./arrange.js";
+import type { Operation } from "./ops/types.js";
+import type { Principal } from "./permissions/types.js";
+import type { AnySchema } from "./schema/schema.js";
+import type { AnyNodeDefinition } from "./schema/types.js";
+import type { Store } from "./store.js";
+import type { Place } from "./views/types.js";
+/**
+ * SEARCH IS ONE SEAM, and the graph is the result list.
+ *
+ * A person asks a picture of a domain four things — where is the thing
+ * called X, where do I go for X, what can I do about X, what is X tied to —
+ * and the framework answered pieces of each in different places with
+ * different code: the list page's `?q=`, the inspector's searcher over acts,
+ * the conversation's "a node named in the message", the arrangement's `q`.
+ * This is the one matcher behind all of them. It is headless, derived from
+ * the declaration (what `readableFields` would show is what is searchable;
+ * `display.hide` is the opt-out), policy-honest (what a seat may not see is
+ * not a hit) and not fuzzy: a typo is answered with nothing and the words
+ * shown back, which is honest and cheap. See docs/search.md.
+ */
+/** How a hit matched, strongest first. */
+export type MatchStrength = "exact" | "prefix" | "word" | "part" | "field";
+/** Why a hit is shown: the field that matched and the words around the match. */
+export interface Why {
+    /** `label`, a field name, `plural`, `title` or `name`. */
+    readonly field: string;
+    /** The field as it reads: "Notes", "Name", "Title". */
+    readonly reading: string;
+    /** The matching text, cut to a window around the first match: "…the van on Friday…". */
+    readonly fragment: string;
+    readonly strength: MatchStrength;
+}
+export type Hit = {
+    readonly about: "node";
+    readonly id: string;
+    readonly kind: string;
+    readonly label: string;
+    readonly why: Why;
+    /** False for a record its kind's lifecycle has retired; only seen under `is:any` or `is:past`. */
+    readonly current: boolean;
+    readonly flagged: boolean;
+    /** What tells it apart from another hit of the same name — "single" beside "album". */
+    readonly apart?: string;
+} | {
+    readonly about: "kind";
+    readonly kind: string;
+    /** The plural, as a district is headed. */
+    readonly label: string;
+    readonly why: Why;
+    /** How many node hits are of this kind. */
+    readonly count: number;
+} | {
+    readonly about: "place";
+    readonly kind: string;
+    readonly title: string;
+    /** The place's name in a stop. */
+    readonly as: string;
+    readonly why: Why;
+} | {
+    readonly about: "act";
+    readonly name: string;
+    readonly title: string;
+    /** The node the act would be offered on — an act is never a subjectless hit. */
+    readonly subject: string;
+    readonly why: Why;
+    readonly destructive: boolean;
+} | {
+    readonly about: "rule";
+    readonly name: string;
+    readonly label: string;
+    /** The kind the rule judges, when it is scoped to one. */
+    readonly kind?: string;
+    readonly why: Why;
+};
+export type HitAbout = Hit["about"];
+/** A `key:value` token from the query, and which kinds it applied to. */
+export interface SearchCondition extends Condition {
+    /** The searched kinds that can be narrowed by it; the rest ignore it. */
+    readonly admittedBy: readonly string[];
+}
+export interface SearchResult {
+    readonly hits: readonly Hit[];
+    /** The words, without the conditions, as typed. */
+    readonly words: string;
+    readonly conditions: readonly SearchCondition[];
+    /** What was looked through: the kinds (after `kind:` and the policy) and whether past records were. */
+    readonly searched: {
+        readonly kinds: readonly string[];
+        readonly past: boolean;
+    };
+    /** Node hits per kind, before the limit — what a district counts at altitude. */
+    readonly byKind: Readonly<Record<string, number>>;
+    /** Node hits in all, before the limit. */
+    readonly total: number;
+    /**
+     * Every matching record's id, in rank order, before the limit — what a
+     * picture lights. The hits are an index to read; this is the answer to
+     * "is this one of them", and a capped list would dim real matches.
+     */
+    readonly matched: readonly string[];
+}
+export interface SearchOptions {
+    /** Who is looking. A kind this principal may not see yields no hits of any sort. */
+    readonly principal?: Principal;
+    /** The subject: the selection, the focus, the pointer's settle. A record one edge from it ranks first in its tier. */
+    readonly from?: readonly string[];
+    /**
+     * The kind the person is in — the district they went into, or the kind of
+     * the record they are on. Its records lead the others of the same
+     * strength: "Gone Digital" typed inside the songs is the song, not the
+     * album that happens to sort first.
+     */
+    readonly inKind?: string;
+    /** The node hit that is highlighted; its acts become hits. */
+    readonly subject?: string;
+    /** The places the view registry names — the store cannot see pictures. */
+    readonly places?: readonly Place[];
+    /** Node ids the rules implicate. Read off the store's violations when absent. */
+    readonly flagged?: ReadonlySet<string>;
+    /** YYYY-MM-DD, for the lifecycle. */
+    readonly today?: string;
+    /**
+     * What the op log touched lately (`touchWeights`), when the caller holds
+     * it — a Find box asks on every keystroke, and the log only changes when
+     * the graph does.
+     */
+    readonly touched?: ReadonlyMap<string, number>;
+    /**
+     * The kinds to look in, when fewer than all the seat may see: the scene
+     * looks only in the districts it draws. Never widens past the policy.
+     */
+    readonly kinds?: readonly string[];
+    /** Most hits returned; counts are taken before it. 50 when unsaid. */
+    readonly limit?: number;
+}
+/** Lower case, diacritics dropped, every run of punctuation a single space. */
+export declare function fold(text: string): string;
+/** Folded, then with the spaces gone: what `exact` and `prefix` compare. */
+export declare function squeeze(text: string): string;
+/**
+ * How strongly `text` answers the words, or undefined when it does not.
+ *
+ * Every word has to be found, each as the start of a word of the text —
+ * `van` finds "Book the van" and "vans", never "caravan". Exact and prefix
+ * are judged on the squeezed whole, so "book the" is a prefix of "Book the
+ * van" however it was punctuated.
+ */
+export declare function strengthOf(text: string, words: readonly string[]): Exclude<MatchStrength, "field"> | undefined;
+/** The text around the first word's match, with an ellipsis where it was cut. */
+export declare function fragmentOf(text: string, words: readonly string[], width?: number): string;
+export interface ParsedQuery {
+    readonly words: string;
+    readonly conditions: readonly Condition[];
+}
+export declare function parseQuery(query: string): ParsedQuery;
+/**
+ * What a kind is searched by, from its declaration alone: the name, and
+ * every field a person would read on a record — which is to say every
+ * field but the hidden and the ones with no one-line rendering. For
+ * `describe` and llms.txt, so an agent knows what the words reach.
+ */
+export declare function searchableFields(schema: AnySchema, kind: string): readonly {
+    readonly key: string;
+    readonly reading: string;
+}[];
+/**
+ * Whether a node answers the words, and why.
+ *
+ * The label is judged first and whole; failing that, every word has to be
+ * found somewhere on the node — "van large" finds the large job about the
+ * van — and the why names the field that carried a word the label did not.
+ */
+export declare function matchNode(definition: AnyNodeDefinition | undefined, node: {
+    id: string;
+    kind: string;
+} & Record<string, unknown>, words: string): Why | undefined;
+export declare function touchWeights(ops: readonly Operation[]): ReadonlyMap<string, number>;
+/**
+ * Finds what the words name, anywhere in the graph, for one seat.
+ *
+ * Node hits are records whose label or readable fields carry every word;
+ * kind, place and rule hits are what the words name in the declaration;
+ * act hits are the acts the seat may run on `subject`, the highlighted
+ * node hit — never subjectless. A declaration hit leads only when the words
+ * name it exactly or as a prefix; otherwise the records lead.
+ *
+ * Ranking, stable: how the words matched (exact label, label prefix, whole
+ * words of the label, parts of it, a field), then near the subject, then
+ * current before past, then recently touched, then flagged before clear,
+ * then alphabetical, then by id.
+ */
+export declare function search<S extends AnySchema>(store: Store<S>, query: string, options?: SearchOptions): SearchResult;
+/**
+ * WHAT CAN BE DONE ABOUT IT: the acts a seat may run on one record, as
+ * hits. An act is never a subjectless hit — it is offered on the thing the
+ * person highlighted, with its own title — and the words that name the
+ * record may name the act too ("van finish"), so each act is judged on the
+ * words its own title carries. The named first, the destructive last.
+ *
+ * Its own function because a Find box asks it for a highlighted row on
+ * every keystroke, and has no need to rescan the graph to get it.
+ */
+export declare function actsOn<S extends AnySchema>(store: Store<S>, subjectId: string, words: string, options?: {
+    readonly principal?: Principal;
+    readonly limit?: number;
+}): readonly Extract<Hit, {
+    about: "act";
+}>[];
+/**
+ * The sentence for what was searched, for an empty state or a strip's
+ * footer: "Tasks and lists, current ones; add is:any for past ones."
+ */
+export declare function describeSearched(schema: AnySchema, searched: SearchResult["searched"]): string;
+//# sourceMappingURL=search.d.ts.map

package/dist/search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../src/search.ts"],"names":[],"mappings":"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"}

package/dist/search.js

@@ -0,0 +1,449 @@
+import { arrangeable, asksForThePast, conditionHolds } from "./arrange.js";
+import { describeArg } from "./mutations/node-ref.js";
+import { humaniseField, isCurrent, labelOf, readableFields, tellApart } from "./schema/define-node.js";
+/*
+ * SQUEEZED TEXT. Case, diacritics and punctuation aside — "Café-Noir" and
+ * "cafe noir" are the same words to a person typing. Words stay separate,
+ * because token alignment is what keeps "bo" out of "elbow".
+ */
+/** Lower case, diacritics dropped, every run of punctuation a single space. */
+export function fold(text) {
+    return text
+        .normalize("NFD")
+        .replace(/\p{M}+/gu, "")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .trim();
+}
+/** Folded, then with the spaces gone: what `exact` and `prefix` compare. */
+export function squeeze(text) {
+    return fold(text).replace(/ /g, "");
+}
+const tokensOf = (text) => fold(text).split(" ").filter(Boolean);
+/**
+ * How strongly `text` answers the words, or undefined when it does not.
+ *
+ * Every word has to be found, each as the start of a word of the text —
+ * `van` finds "Book the van" and "vans", never "caravan". Exact and prefix
+ * are judged on the squeezed whole, so "book the" is a prefix of "Book the
+ * van" however it was punctuated.
+ */
+export function strengthOf(text, words) {
+    if (words.length === 0)
+        return undefined;
+    const whole = squeeze(text);
+    const asked = words.join("");
+    if (whole.length === 0)
+        return undefined;
+    if (whole === asked)
+        return "exact";
+    const own = tokensOf(text);
+    const found = words.every((word) => own.some((token) => token.startsWith(word)));
+    if (!found)
+        return undefined;
+    if (whole.startsWith(asked))
+        return "prefix";
+    return words.every((word) => own.includes(word)) ? "word" : "part";
+}
+/** The text around the first word's match, with an ellipsis where it was cut. */
+export function fragmentOf(text, words, width = 48) {
+    if (text.length <= width)
+        return text;
+    const first = words[0];
+    const folded = text.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+    const at = first ? folded.search(new RegExp(`(^|[^\\p{L}\\p{N}])${escape(first)}`, "u")) : -1;
+    const hit = at < 0 ? 0 : at + (folded[at] && /[\p{L}\p{N}]/u.test(folded[at]) ? 0 : 1);
+    let start = Math.max(0, hit - Math.floor(width / 3));
+    // Start on a word, not in one.
+    if (start > 0) {
+        const space = text.lastIndexOf(" ", start);
+        start = space < 0 ? 0 : space + 1;
+    }
+    let end = Math.min(text.length, start + width);
+    if (end < text.length) {
+        const space = text.indexOf(" ", end);
+        end = space < 0 || space - end > 16 ? end : space;
+    }
+    return `${start > 0 ? "…" : ""}${text.slice(start, end).trim()}${end < text.length ? "…" : ""}`;
+}
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const CONDITION = /^([\p{L}][\p{L}\p{N}_-]*):(\S+)$/u;
+export function parseQuery(query) {
+    const words = [];
+    const conditions = [];
+    for (const token of query.trim().split(/\s+/).filter(Boolean)) {
+        const match = CONDITION.exec(token);
+        if (match)
+            conditions.push({ key: match[1], value: match[2] });
+        else
+            words.push(token);
+    }
+    return { words: words.join(" "), conditions };
+}
+function textsOf(definition, node) {
+    const label = labelOf(definition, node);
+    const texts = [{ field: "label", reading: "Name", text: label }];
+    for (const field of readableFields(node, definition, { limit: Number.POSITIVE_INFINITY })) {
+        if (field.key === "label" || field.value === label)
+            continue;
+        /*
+         * A BOOLEAN IS A STATE, NOT A WORD. It reads as "Yes" or "No", and
+         * searching that made "n" — the first letter of anything — find every
+         * open task. A state is asked for as a condition: `done:false`.
+         */
+        if (typeof node[field.key] === "boolean")
+            continue;
+        texts.push({ field: field.key, reading: field.label, text: field.value });
+    }
+    return texts;
+}
+/**
+ * What a kind is searched by, from its declaration alone: the name, and
+ * every field a person would read on a record — which is to say every
+ * field but the hidden and the ones with no one-line rendering. For
+ * `describe` and llms.txt, so an agent knows what the words reach.
+ */
+export function searchableFields(schema, kind) {
+    const definition = schema.tryDefinition(kind);
+    if (!definition)
+        return [];
+    const hidden = new Set(definition.display?.hide ?? []);
+    const fields = [{ key: "label", reading: "Name" }];
+    for (const [key, field] of Object.entries((definition.fields.shape ?? {}))) {
+        if (key === "id" || key === "kind" || key === "label" || hidden.has(key))
+            continue;
+        const type = describeArg(field).type;
+        // A state is a condition (`done:false`), not a word to find; see textsOf.
+        if (type === "boolean")
+            continue;
+        if (type === "unknown" && definition.display?.format?.[key] === undefined)
+            continue;
+        fields.push({ key, reading: definition.display?.labels?.[key] ?? humaniseField(key) });
+    }
+    return fields;
+}
+const TIER = { exact: 0, prefix: 1, word: 2, part: 3, field: 4 };
+/**
+ * Whether a node answers the words, and why.
+ *
+ * The label is judged first and whole; failing that, every word has to be
+ * found somewhere on the node — "van large" finds the large job about the
+ * van — and the why names the field that carried a word the label did not.
+ */
+export function matchNode(definition, node, words) {
+    const asked = tokensOf(words);
+    if (asked.length === 0)
+        return undefined;
+    const texts = textsOf(definition, node);
+    const [label, ...rest] = texts;
+    const onLabel = strengthOf(label.text, asked);
+    if (onLabel)
+        return { field: "label", reading: label.reading, fragment: fragmentOf(label.text, asked), strength: onLabel };
+    const everywhere = (word) => (text) => tokensOf(text.text).some((token) => token.startsWith(word));
+    if (!asked.every((word) => texts.some(everywhere(word))))
+        return undefined;
+    const labelTokens = tokensOf(label.text);
+    const carried = asked.find((word) => !labelTokens.some((token) => token.startsWith(word))) ?? asked[0];
+    const field = rest.find(everywhere(carried));
+    return { field: field.field, reading: field.reading, fragment: fragmentOf(field.text, [carried]), strength: "field" };
+}
+/*
+ * RECENTLY TOUCHED. What the op log wrote lately, decaying by log distance
+ * the way the menu's usage boost does, so a record worked on this morning
+ * ranks above its twin untouched since spring — a tiebreak, never a tier.
+ */
+const WINDOW = 512;
+const HALF_LIFE = 64;
+export function touchWeights(ops) {
+    const weights = new Map();
+    if (ops.length === 0)
+        return weights;
+    const tail = ops.slice(-WINDOW);
+    const last = ops[ops.length - 1].seq;
+    for (const op of tail) {
+        const weight = Math.pow(0.5, (last - op.seq) / HALF_LIFE);
+        for (const id of op.writes)
+            weights.set(id, (weights.get(id) ?? 0) + weight);
+    }
+    return weights;
+}
+const pluralOf = (definition, kind) => definition?.plural ?? `${humaniseField(kind)}s`;
+/** Whether the words name this kind: its id, its singular in words, or its plural. */
+function kindStrength(schema, kind, words) {
+    const definition = schema.tryDefinition(kind);
+    const candidates = [
+        { field: "plural", text: pluralOf(definition, kind) },
+        { field: "kind", text: humaniseField(kind) },
+        ...(definition?.noun ? [{ field: "noun", text: definition.noun }] : []),
+    ];
+    let best;
+    for (const candidate of candidates) {
+        const strength = strengthOf(candidate.text, words);
+        if (strength && (!best || TIER[strength] < TIER[best.strength]))
+            best = { strength, ...candidate };
+    }
+    return best;
+}
+/** The ranking, as one comparison: how it matched, the kind the person is in, near, current, touched, flagged, alphabetical, id. */
+const byRank = (a, b) => a.tier - b.tier ||
+    a.inKind - b.inKind ||
+    a.near - b.near ||
+    a.past - b.past ||
+    a.touched - b.touched ||
+    a.flagged - b.flagged ||
+    a.name.localeCompare(b.name, undefined, { sensitivity: "base", numeric: true }) ||
+    (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+ * Finds what the words name, anywhere in the graph, for one seat.
+ *
+ * Node hits are records whose label or readable fields carry every word;
+ * kind, place and rule hits are what the words name in the declaration;
+ * act hits are the acts the seat may run on `subject`, the highlighted
+ * node hit — never subjectless. A declaration hit leads only when the words
+ * name it exactly or as a prefix; otherwise the records lead.
+ *
+ * Ranking, stable: how the words matched (exact label, label prefix, whole
+ * words of the label, parts of it, a field), then near the subject, then
+ * current before past, then recently touched, then flagged before clear,
+ * then alphabetical, then by id.
+ */
+export function search(store, query, options = {}) {
+    const schema = store.schema;
+    const parsed = parseQuery(query);
+    const words = tokensOf(parsed.words);
+    const principal = options.principal ?? { kind: "human" };
+    const kept = store.kindsKeptFrom(principal);
+    const off = store.modules.disabledKinds;
+    const kindWords = parsed.conditions.filter((condition) => condition.key === "kind").map((condition) => condition.value);
+    const isWords = parsed.conditions.filter((condition) => condition.key === "is").map((condition) => condition.value);
+    const past = isWords.includes("any") || isWords.includes("past");
+    const onlyPast = isWords.includes("past") && !isWords.includes("any") && !isWords.includes("current");
+    const named = (kind, value) => {
+        const asked = squeeze(value);
+        const definition = schema.tryDefinition(kind);
+        return squeeze(kind) === asked || squeeze(pluralOf(definition, kind)) === asked;
+    };
+    const kinds = schema.kinds.filter((kind) => !kept.has(kind) &&
+        !off.has(kind) &&
+        (options.kinds === undefined || options.kinds.includes(kind)) &&
+        (kindWords.length === 0 || kindWords.some((value) => named(kind, value))));
+    // The rest of the conditions narrow the kinds whose declaration offers them.
+    const narrowing = parsed.conditions.filter((condition) => condition.key !== "kind");
+    const conditions = narrowing.map((condition) => ({
+        ...condition,
+        admittedBy: kinds.filter((kind) => arrangeable(schema, kind).filters.some((offer) => offer.key === condition.key)),
+    }));
+    const fieldConditions = conditions.filter((condition) => condition.key !== "is");
+    // `is:flagged`, `is:clear` and `is:past` narrow on their own; `is:any` and `is:current` only say which horizon.
+    const narrowingIs = isWords.filter((word) => word === "flagged" || word === "clear" || word === "past");
+    const searched = { kinds, past };
+    const empty = { hits: [], words: parsed.words, conditions, searched, byKind: {}, total: 0, matched: [] };
+    if (words.length === 0 && fieldConditions.length === 0 && narrowingIs.length === 0)
+        return empty;
+    const today = options.today;
+    const flagged = options.flagged ?? new Set(store.violations().flatMap((violation) => violation.nodeIds));
+    const touched = options.touched ?? touchWeights(store.log.all());
+    const near = new Set();
+    for (const id of options.from ?? []) {
+        near.add(id);
+        for (const neighbour of store.graph.neighbors(id))
+            near.add(neighbour.id);
+    }
+    // The same words mean the same thing in a search box and in a list page's filter.
+    const ctx = { schema, graph: store.graph, flagged, ...(today ? { today } : {}) };
+    const ranked = [];
+    const byKind = {};
+    for (const kind of kinds) {
+        const definition = schema.tryDefinition(kind);
+        const own = conditions.filter((condition) => condition.key !== "is" && condition.admittedBy.includes(kind));
+        // Conditions alone find only in the kinds that can be narrowed by them.
+        if (words.length === 0 && own.length === 0 && narrowingIs.length === 0)
+            continue;
+        /*
+         * A CONDITION THAT NAMES A RETIRED STATE ASKS FOR THE PAST. `status:demo`
+         * on a discography whose demos are behind the horizon found nothing and
+         * said "add is:any" — to somebody who had just named the past by name.
+         */
+        const namesThePast = asksForThePast(definition, own);
+        for (const node of store.graph.nodesOfKind(kind)) {
+            const current = isCurrent(definition, node, today);
+            if (!past && !namesThePast && !current)
+                continue;
+            if (onlyPast && current)
+                continue;
+            if (!own.every((condition) => conditionHolds(ctx, node, condition)))
+                continue;
+            if (isWords.includes("flagged") && !flagged.has(node.id))
+                continue;
+            if (isWords.includes("clear") && flagged.has(node.id))
+                continue;
+            const why = words.length > 0
+                ? matchNode(definition, node, parsed.words)
+                : own[0]
+                    ? { field: own[0].key, reading: humaniseField(own[0].key), fragment: `${own[0].key}:${own[0].value}`, strength: "field" }
+                    : { field: "is", reading: "Is", fragment: `is:${narrowingIs[0]}`, strength: "field" };
+            if (!why)
+                continue;
+            const label = labelOf(definition, node);
+            byKind[kind] = (byKind[kind] ?? 0) + 1;
+            ranked.push({
+                hit: { about: "node", id: node.id, kind, label, why, current, flagged: flagged.has(node.id) },
+                tier: TIER[why.strength],
+                inKind: kind === options.inKind ? 0 : 1,
+                near: near.has(node.id) ? 0 : 1,
+                past: current ? 0 : 1,
+                touched: -(touched.get(node.id) ?? 0),
+                flagged: flagged.has(node.id) ? 0 : 1,
+                name: label,
+                id: node.id,
+            });
+        }
+    }
+    /*
+     * THE DECLARATION'S HITS: a kind, a place, a rule. They lead the records
+     * only when the words name them exactly or as a prefix — "tasks" is the
+     * district, "van" is a record that happens to share a letter with nothing.
+     */
+    const lead = (strength) => (strength === "exact" || strength === "prefix" ? -1 : TIER[strength]);
+    const declared = (hit, strength, name, id) => ({
+        hit,
+        tier: lead(strength),
+        inKind: 1,
+        near: 1,
+        past: 0,
+        touched: 0,
+        flagged: 1,
+        name,
+        id,
+    });
+    if (words.length > 0) {
+        for (const kind of kinds) {
+            const match = kindStrength(schema, kind, words);
+            if (!match)
+                continue;
+            const label = pluralOf(schema.tryDefinition(kind), kind);
+            const why = { field: match.field, reading: match.field === "plural" ? "Plural" : "Kind", fragment: match.text, strength: match.strength };
+            ranked.push(declared({ about: "kind", kind, label, why, count: byKind[kind] ?? 0 }, match.strength, label, `kind:${kind}`));
+        }
+        for (const place of options.places ?? []) {
+            if (!kinds.includes(place.kind) || (place.across && kept.has(place.across)))
+                continue;
+            const strength = strengthOf(place.title, words);
+            if (!strength)
+                continue;
+            const why = { field: "title", reading: "Title", fragment: place.title, strength };
+            ranked.push(declared({ about: "place", kind: place.kind, title: place.title, as: place.as, why }, strength, place.title, `place:${place.kind}:${place.as}`));
+        }
+        for (const rule of store.allInvariants()) {
+            const scoped = rule.scope === "graph" ? undefined : rule.scope.kind;
+            if (scoped && !kinds.includes(scoped))
+                continue;
+            const label = rule.label ?? humaniseField(rule.name);
+            const onLabel = strengthOf(label, words);
+            const onName = onLabel ? undefined : strengthOf(humaniseField(rule.name), words);
+            const strength = onLabel ?? onName;
+            if (!strength)
+                continue;
+            const why = { field: onLabel ? "label" : "name", reading: onLabel ? "Rule" : "Name", fragment: onLabel ? label : rule.name, strength };
+            ranked.push(declared({ about: "rule", name: rule.name, label, ...(scoped ? { kind: scoped } : {}), why }, strength, label, `rule:${rule.name}`));
+        }
+    }
+    ranked.sort(byRank);
+    const limit = options.limit ?? 50;
+    const shown = ranked.slice(0, limit).map((entry) => entry.hit);
+    /*
+     * Two hits of one name say what tells them apart — a single and its
+     * album, both "Blue Hour", by the fact that differs; a song and an album,
+     * both "Gone Digital", by their nouns. Across kinds too: the strip heads
+     * each kind, but a row is read alone — by the pointer that lands on it,
+     * by the screen reader that speaks it — and "Gone Digital, Gone Digital"
+     * is a choice nobody can make.
+     */
+    const alike = shown.flatMap((hit) => (hit.about === "node" ? [store.graph.getNode(hit.id)] : [])).filter(Boolean);
+    const apart = tellApart(alike, (named) => schema.tryDefinition(named));
+    const hits = shown.map((hit) => (hit.about === "node" && apart.has(hit.id) ? { ...hit, apart: apart.get(hit.id) } : hit));
+    const total = Object.values(byKind).reduce((sum, count) => sum + count, 0);
+    const matched = ranked.flatMap((entry) => (entry.hit.about === "node" ? [entry.hit.id] : []));
+    const acts = options.subject && kinds.includes(String(store.graph.getNode(options.subject)?.kind)) ? actsOn(store, options.subject, parsed.words, { principal }) : [];
+    return {
+        hits: [...hits, ...acts],
+        words: parsed.words,
+        conditions,
+        searched,
+        byKind,
+        total,
+        matched,
+    };
+}
+/**
+ * WHAT CAN BE DONE ABOUT IT: the acts a seat may run on one record, as
+ * hits. An act is never a subjectless hit — it is offered on the thing the
+ * person highlighted, with its own title — and the words that name the
+ * record may name the act too ("van finish"), so each act is judged on the
+ * words its own title carries. The named first, the destructive last.
+ *
+ * Its own function because a Find box asks it for a highlighted row on
+ * every keystroke, and has no need to rescan the graph to get it.
+ */
+export function actsOn(store, subjectId, words, options = {}) {
+    const subject = store.graph.getNode(subjectId);
+    if (!subject)
+        return [];
+    const principal = options.principal ?? { kind: "human" };
+    if (store.kindsKeptFrom(principal).has(subject.kind))
+        return [];
+    const asked = tokensOf(words);
+    const said = labelOf(store.schema.tryDefinition(subject.kind), subject);
+    const ranked = [];
+    for (const mutation of store.allMutations()) {
+        const binding = mutation.subject;
+        if (!binding)
+            continue;
+        if (binding.kinds !== "*" && !binding.kinds.includes(subject.kind))
+            continue;
+        if (!store.permits({ name: mutation.name, args: { [binding.arg]: subject.id } }, principal).ok)
+            continue;
+        const title = mutation.title ?? humaniseField(mutation.name);
+        const titled = tokensOf(title);
+        const own = asked.filter((word) => titled.some((token) => token.startsWith(word)));
+        const strength = own.length > 0 ? strengthOf(title, own) : undefined;
+        const why = strength
+            ? { field: "title", reading: "Act", fragment: title, strength }
+            : { field: "subject", reading: "On", fragment: said, strength: "field" };
+        ranked.push({
+            hit: { about: "act", name: mutation.name, title, subject: subject.id, why, destructive: mutation.destructive === true },
+            tier: strength ? TIER[strength] : TIER.field + 1,
+            inKind: 0,
+            near: 0,
+            past: mutation.destructive ? 1 : 0,
+            touched: 0,
+            flagged: mutation.pinned ? 0 : 1,
+            name: title,
+            id: `act:${mutation.name}`,
+        });
+    }
+    ranked.sort(byRank);
+    const acts = ranked.map((entry) => entry.hit);
+    return options.limit === undefined ? acts : acts.slice(0, options.limit);
+}
+/**
+ * The sentence for what was searched, for an empty state or a strip's
+ * footer: "Tasks and lists, current ones; add is:any for past ones."
+ */
+export function describeSearched(schema, searched) {
+    const plurals = searched.kinds.map((kind, index) => {
+        const plural = pluralOf(schema.tryDefinition(kind), kind);
+        return index === 0 ? plural : plural.toLowerCase();
+    });
+    const names = plurals.length === 0
+        ? "Nothing"
+        : plurals.length === 1
+            ? plurals[0]
+            : `${plurals.slice(0, -1).join(", ")} and ${plurals[plurals.length - 1]}`;
+    const lifecycled = searched.kinds.some((kind) => schema.tryDefinition(kind)?.lifecycle);
+    if (!lifecycled)
+        return `${capitalFirst(names)}.`;
+    return searched.past ? `${capitalFirst(names)}, past ones included.` : `${capitalFirst(names)}, current ones; add is:any for past ones.`;
+}
+const capitalFirst = (text) => text.charAt(0).toUpperCase() + text.slice(1);
+//# sourceMappingURL=search.js.map