spexcode 0.6.1 → 0.6.5

package/node_modules/@spexcode/spec-core/dist/review/reviewFilters.js

@@ -0,0 +1,308 @@
+import { sessionHeadline, sessionPresent } from './session.js';
+import { effectiveTokens, tokenize } from './reviewQuery.js';
+// [[review-filters]]: one pure filter engine — the single home of Issues/Evals FIELD SEMANTICS. Domain
+// adapters below provide field values; surfaces provide only the state home and presentation: the
+// canonical pages parse their ONE visible token text ([[review-query]]) and bridge it here, the Spec
+// Information panes keep plain local state. Neither duplicates matching.
+const text = (value) => String(value ?? '').trim().toLocaleLowerCase();
+const values = (value) => (Array.isArray(value) ? value : value == null || value === '' ? [] : [value]);
+const unique = (items) => [...new Set(items.flatMap(values).filter((value) => value != null && value !== '').map(String))];
+export const EVAL_FILTER_KIND = Object.freeze({
+    RESULT: 'result',
+    BLIND: 'blind',
+    UNMEASURED: 'unmeasured',
+    DANGLING: 'dangling',
+});
+export const evidenceList = (reading) => reading?.evidence?.length ? reading.evidence
+    : reading?.blob != null ? [{ hash: reading.blob, kind: reading.blobKind || 'image', state: reading.blobState || 'present' }]
+        : [];
+export const kindsOf = (reading) => {
+    const evidence = evidenceList(reading);
+    if (!evidence.length)
+        return ['note'];
+    return ['video', 'image', 'transcript', 'data'].filter((kind) => evidence.some((item) => item.kind === kind));
+};
+const optionLabel = (t, key, fallback) => t ? t(key) : fallback;
+const allOption = (t) => ({ value: '', label: optionLabel(t, 'reviewList.all', 'All') });
+const optionsFor = (items, facet, state, context, t) => {
+    const active = state[facet.key] != null && String(state[facet.key]) !== '';
+    // a fixed-value ENUM facet keeps its ACTIVE value as a real (checked) row even when no data carries
+    // it — an active facet must never hide its own off-switch; data-valued facets stay data-derived.
+    const found = facet.fixedValues
+        ? facet.fixedValues.filter((value) => facet.enumerateFixed
+            || (active && String(state[facet.key]) === String(value))
+            || items.some((item) => values(facet.values(item, context)).map(String).includes(String(value))))
+        : unique(items.map((item) => facet.values(item, context)));
+    const available = facet.available
+        ? facet.available(found, items, state, context)
+        : found.length >= (facet.minValues ?? 2);
+    if (!available && !active)
+        return [];
+    return [allOption(t), ...found.map((value) => ({
+            value,
+            label: facet.labelValue ? facet.labelValue(value, context) : value,
+        }))];
+};
+// A SPLIT section reports its count as two named buckets instead of one number. The predicate is BINARY
+// and applied to the section's own matched rows, so the buckets always re-add to that section's whole
+// population — a surface can lead with one half without the count quietly shrinking. The adapter alone
+// decides which sections split and on what axis; the engine invents no bucket.
+const splitCount = (matched, split, context) => {
+    const first = matched.filter((item) => split.is(item, context)).length;
+    return { [split.keys[0]]: first, [split.keys[1]]: matched.length - first };
+};
+// the one reading rule for a section count, whichever shape the adapter declared.
+export const sectionTotal = (count) => (typeof count === 'number'
+    ? count
+    : Object.values(count ?? {}).reduce((sum, value) => sum + value, 0));
+export function filterReviewItems(items, state, config, context = {}) {
+    // `q` is one substring or an ARRAY of substrings (the token text's bare words/phrases), conjunctive;
+    // an `impossible` state (an unknown qualifier in the canonical text) honestly matches NOTHING.
+    const qs = values(state.q).map(text).filter(Boolean);
+    const faceted = state.impossible ? [] : items.filter((item) => (qs.every((q) => config.search(item, context).some((value) => text(value).includes(q)))
+        && config.facets.every((facet) => {
+            const selected = state[facet.key];
+            return selected == null || selected === ''
+                || (facet.matches
+                    ? facet.matches(item, selected, context)
+                    : values(facet.values(item, context)).map(String).includes(String(selected)));
+        })));
+    const sectionValue = config.section && state[config.section.key];
+    const sectionMatch = (item, selected) => (config.section.matches
+        ? config.section.matches(item, selected, context)
+        : String(config.section.value(item, context)) === String(selected));
+    const shown = sectionValue == null || sectionValue === ''
+        ? faceted
+        : faceted.filter((item) => sectionMatch(item, sectionValue));
+    const sections = config.section
+        ? Object.fromEntries(config.section.options.map((option) => {
+            const matched = faceted.filter((item) => sectionMatch(item, option.value));
+            return [option.value, option.split && config.section.split
+                    ? splitCount(matched, config.section.split, context)
+                    : matched.length];
+        }))
+        : {};
+    const facets = Object.fromEntries(config.facets.map((facet) => [facet.key, {
+            key: facet.key,
+            label: optionLabel(context.t, facet.label, facet.key),
+            value: state[facet.key] || '',
+            options: optionsFor(items, facet, state, context, context.t),
+        }]));
+    return { state, faceted, shown, sections, facets };
+}
+export const reviewActorName = (actor) => String(actor || '').length > 22 ? `${String(actor).slice(0, 8)}…` : actor;
+// the source-session PRESENCE join ([[live-session-filter]]): originator or any reply author still
+// resolves on the board — membership, never liveness.
+const issuePresent = (issue, sessions) => !!sessionPresent(sessions, issue.by)
+    || (Array.isArray(issue.replies) && issue.replies.some((reply) => sessionPresent(sessions, reply.by)));
+const presenceFacet = (valuesOf) => ({
+    key: 'session', label: 'reviewList.facetSession', fixedValues: ['present', 'missing'],
+    values: valuesOf,
+    labelValue: (value, { t }) => optionLabel(t, value === 'present' ? 'reviewList.sessionPresent' : 'reviewList.sessionMissing', value),
+});
+export function issueFilterState(raw = {}, { defaultSection = '' } = {}) {
+    const state = raw.state === 'closed' || raw.concluded === '1'
+        ? 'closed'
+        : raw.state || defaultSection;
+    return {
+        q: raw.q || '', state, impossible: raw.impossible === true,
+        author: raw.author || '', store: raw.store || '', node: raw.node || '', label: raw.label || '',
+        session: raw.session || '',
+    };
+}
+const ISSUE_CONFIG = {
+    search: (issue) => [issue.id, issue.concern, issue.by, ...(issue.nodes || [])],
+    section: {
+        key: 'state',
+        value: (issue) => issue.status === 'open' ? 'open' : 'closed',
+        // open|closed are the lifecycle halves; a concrete concluded spelling (landed) matches that status
+        // honestly instead of pretending the enum is binary.
+        matches: (issue, selected) => (selected === 'open' ? issue.status === 'open'
+            : selected === 'closed' ? issue.status !== 'open' : issue.status === selected),
+        options: [{ value: 'open', label: 'reviewList.open' }, { value: 'closed', label: 'reviewList.closed' }],
+    },
+    facets: [
+        { key: 'author', label: 'reviewList.facetAuthor', values: (issue) => issue.by, labelValue: reviewActorName },
+        { key: 'store', label: 'reviewList.facetStore', values: (issue) => issue.store },
+        { key: 'node', label: 'reviewList.facetNode', values: (issue) => issue.nodes || [] },
+        { key: 'label', label: 'reviewList.facetLabel', values: (issue) => (issue.labels || []).map((label) => typeof label === 'string' ? label : label?.name), minValues: 1 },
+        presenceFacet((issue, { sessions }) => issuePresent(issue, sessions) ? 'present' : 'missing'),
+    ],
+};
+export function issueFilterModel(items, raw = {}, context = {}) {
+    const state = issueFilterState(raw, { defaultSection: context.defaultSection ?? '' });
+    const model = filterReviewItems(items, state, ISSUE_CONFIG, context);
+    model.section = {
+        key: 'state', label: optionLabel(context.t, 'reviewList.facetState', 'State'), value: state.state,
+        meaningful: Object.values(model.sections).filter((count) => sectionTotal(count) > 0).length > 1 || !!state.state,
+        options: [allOption(context.t), ...ISSUE_CONFIG.section.options.map((option) => ({
+                value: option.value,
+                label: optionLabel(context.t, option.label, option.value),
+                count: sectionTotal(model.sections[option.value]),
+            }))].filter((option, index, all) => index === 0 || option.count > 0 || option.value === state.state),
+    };
+    return model;
+}
+const evalIsResult = (entry) => entry.filterKind === EVAL_FILTER_KIND.RESULT;
+const verdictOf = (entry) => evalIsResult(entry)
+    ? (entry.verdict?.status || 'unscored')
+    : entry.filterKind === EVAL_FILTER_KIND.BLIND || entry.filterKind === EVAL_FILTER_KIND.UNMEASURED
+        ? 'unmeasured'
+        : 'unscored';
+const reviewStateOf = (entry) => (evalIsResult(entry) && entry.fresh && entry.humanOk ? 'reviewed' : 'current');
+// the ONE freshness axis of the Eval adapter — the facet's option values and the verdict sections' split
+// read it, so a chip and its Freshness menu can never disagree about what "stale" counts.
+const evalFresh = (entry) => entry.fresh === true;
+const freshnessOf = (entry) => (evalIsResult(entry) ? (evalFresh(entry) ? 'fresh' : 'stale') : null);
+export const evalReviewState = (reading) => {
+    // an order-only row never had its freshness computed, so it has no verdict to report. Refuse it here
+    // rather than let its conservative placeholder be published as a measured `stalePass`/`staleFail`: the
+    // whole point of the deferred pass is that these rows exist only to establish sequence.
+    if (reading?.freshnessDeferred)
+        throw new Error(`eval row ${reading.scenario ?? '?'} has deferred freshness — it can order a list, never state a verdict`);
+    const status = reading?.verdict?.status;
+    if (status !== 'pass' && status !== 'fail')
+        return 'empty';
+    if (reading.fresh)
+        return status;
+    return status === 'pass' ? 'stalePass' : 'staleFail';
+};
+const shortSession = (value, sessions) => {
+    const session = sessions.find((item) => item.id === value);
+    if (session)
+        return sessionHeadline(session);
+    return String(value || '').length > 22 ? `${String(value).slice(0, 8)}…` : value;
+};
+export function evalFilterState(raw = {}, { defaultKind = 'all', defaultSection = '' } = {}) {
+    const legacyReview = raw.ok === '1' ? 'reviewed' : raw.ok;
+    return {
+        q: raw.q || '', kind: raw.kind || defaultKind, impossible: raw.impossible === true,
+        verdict: raw.verdict || '', freshness: raw.freshness || '', node: raw.node || '', filer: raw.filer || '',
+        session: raw.session || '', review: raw.review || legacyReview || defaultSection,
+    };
+}
+const EVAL_CONFIG = {
+    search: (entry) => [entry.scenario, entry.node, entry.by, entry.evaluator],
+    section: {
+        key: 'verdict', value: verdictOf,
+        // A MEASURED verdict carries a reading, so it also carries freshness: its count splits into the fresh
+        // half and the stale half that still owes a re-measurement. The two halves re-add to the verdict's
+        // whole population — splitting reports the remeasurement debt, it never hides a row. `unmeasured` owns
+        // no reading and therefore no freshness axis, so it stays one honest number.
+        split: { keys: ['fresh', 'stale'], is: evalFresh },
+        options: [
+            { value: 'fail', label: 'reviewList.verdict.fail', split: true },
+            { value: 'pass', label: 'reviewList.verdict.pass', split: true },
+            { value: 'unmeasured', label: 'reviewList.verdict.unmeasured' },
+        ],
+    },
+    facets: [
+        {
+            key: 'review', label: 'reviewList.facetReview', fixedValues: ['current', 'reviewed'], enumerateFixed: true,
+            values: reviewStateOf,
+            labelValue: (value, { t }) => optionLabel(t, value === 'reviewed' ? 'reviewList.reviewed' : 'reviewList.needsReview', value),
+        },
+        {
+            key: 'freshness', label: 'reviewList.facetFreshness', minValues: 2,
+            values: (entry) => freshnessOf(entry) ?? [],
+            labelValue: (value, { t }) => optionLabel(t, `reviewList.freshness.${value}`, value),
+        },
+        {
+            key: 'kind', label: 'reviewList.facetKind', fixedValues: ['video', 'image'], minValues: 1,
+            values: (entry) => evalIsResult(entry) ? kindsOf(entry).filter((kind) => kind === 'video' || kind === 'image') : [],
+            matches: (entry, selected) => selected === 'all' || (evalIsResult(entry) && kindsOf(entry).includes(selected)),
+            labelValue: (value, { t }) => optionLabel(t, `evalsFeed.kind.${value}`, value),
+            available: (found, _items, state) => found.length > 0 || state.kind !== 'all',
+        },
+        { key: 'node', label: 'reviewList.facetNode', values: (entry) => entry.node },
+        {
+            key: 'filer', label: 'reviewList.facetFiler', values: (entry) => evalIsResult(entry) ? entry.by : [],
+            labelValue: (value, { sessions = [] }) => shortSession(value, sessions),
+        },
+        presenceFacet((entry, { sessions }) => (evalIsResult(entry)
+            ? (sessionPresent(sessions, entry.by) ? 'present' : 'missing')
+            : [])),
+    ],
+};
+export function evalFilterModel(items, raw = {}, context = {}) {
+    const state = evalFilterState(raw, {
+        defaultKind: context.defaultKind ?? 'all',
+        defaultSection: context.defaultSection ?? '',
+    });
+    const model = filterReviewItems(items, state, EVAL_CONFIG, context);
+    model.section = {
+        key: 'verdict', label: optionLabel(context.t, 'reviewList.facetVerdict', 'Verdict'), value: state.verdict,
+        meaningful: Object.values(model.sections).some((count) => sectionTotal(count) > 0) || !!state.verdict,
+        // the menu/popup face of the same sections keeps the verdict's WHOLE count: a compact radio row has no
+        // room for the split, and it must still agree with the list it filters.
+        options: [allOption(context.t), ...EVAL_CONFIG.section.options.map((option) => ({
+                value: option.value,
+                label: optionLabel(context.t, option.label, option.value),
+                count: sectionTotal(model.sections[option.value]),
+            }))].filter((option, index) => index === 0 || option.count > 0 || option.value === state.verdict),
+    };
+    const kindFacet = model.facets.kind;
+    if (kindFacet.options.length) {
+        kindFacet.options = [
+            { value: 'all', label: optionLabel(context.t, 'evalsFeed.kind.all', 'All') },
+            ...kindFacet.options.filter((option) => option.value !== '').map((option) => ({ ...option })),
+        ];
+        kindFacet.value = state.kind;
+    }
+    return model;
+}
+export function filterMenuGroups(model, onChange, keys) {
+    return keys.map((key) => key === 'section' ? model.section : model.facets[key]).filter((facet) => (facet?.meaningful !== false
+        && (facet?.options?.length > 1 || (facet?.value != null && facet.value !== '' && facet.value !== 'all')))).map((facet) => ({
+        key: facet.key,
+        label: facet.label,
+        value: facet.value,
+        active: facet.value != null && facet.value !== '' && facet.value !== 'all',
+        options: facet.options,
+        clearLabel: facet.value === 'all' ? null : undefined,
+        onChange: (value) => onChange({ [facet.key]: value || null }),
+    }));
+}
+// the CANONICAL pages' bridge ([[review-query]] → this engine): parse the ONE visible token text into
+// engine state. Bare words/phrases become conjunctive q substrings; duplicate qualifiers are last-wins;
+// a qualifier outside the page's map (or a wrong is: identity) marks the state IMPOSSIBLE — the token
+// stays verbatim in the text and the list honestly shows nothing. `scope:` maps to no filter: it picks
+// the DATA SOURCE upstream ([[evals-view]]), never a per-row predicate.
+const TOKEN_MAPS = {
+    issue: {
+        is: (v) => (v === 'issue' ? {} : null),
+        state: (v) => ({ state: v }),
+        store: (v) => ({ store: v }),
+        author: (v) => ({ author: v }),
+        node: (v) => ({ node: v }),
+        label: (v) => ({ label: v }),
+        session: (v) => ({ session: v }),
+    },
+    eval: {
+        is: (v) => (v === 'eval' ? {} : null),
+        state: (v) => ({ review: v }),
+        verdict: (v) => ({ verdict: v }),
+        freshness: (v) => ({ freshness: v }),
+        evidence: (v) => ({ kind: v }),
+        node: (v) => ({ node: v }),
+        filer: (v) => ({ filer: v }),
+        session: (v) => ({ session: v }),
+        scope: () => ({}),
+    },
+};
+export function tokenFilterState(text, domain) {
+    const map = TOKEN_MAPS[domain];
+    const state = { q: [] };
+    for (const token of effectiveTokens(tokenize(text))) {
+        if (token.key == null) {
+            state.q.push(token.value);
+            continue;
+        }
+        const toState = map[token.key];
+        const mapped = toState ? toState(token.value) : null;
+        if (mapped == null)
+            return { impossible: true, q: [] };
+        Object.assign(state, mapped);
+    }
+    return state;
+}

package/node_modules/@spexcode/spec-core/dist/review/reviewQuery.d.ts

@@ -0,0 +1,66 @@
+export function scanQuery(text: any): ({
+    ws: boolean;
+    raw: string;
+    start: number;
+    end: number;
+    key?: undefined;
+    value?: undefined;
+} | {
+    ws: boolean;
+    raw: string;
+    start: number;
+    end: number;
+    key: string;
+    value: any;
+} | {
+    ws: boolean;
+    raw: string;
+    start: number;
+    end: number;
+    key: null;
+    value: any;
+})[];
+export function setToken(text: any, key: any, value: any): any;
+export function legacyQueryText(defaultText: any, query: any): any;
+export function suggestAt(text: any, caret: any, keys?: any[], values?: {}): {
+    start: number;
+    end: number;
+    items: any;
+};
+export const ISSUE_QUERY_DEFAULT: "is:issue state:open";
+export const EVAL_QUERY_DEFAULT: "is:eval";
+export function scopedEvalQuery(sessionId: any): any;
+export function nodeEvalQuery(nodeId: any): any;
+export function quoteValue(v: any): string;
+export function tokenize(text: any): ({
+    ws: boolean;
+    raw: string;
+    start: number;
+    end: number;
+    key?: undefined;
+    value?: undefined;
+} | {
+    ws: boolean;
+    raw: string;
+    start: number;
+    end: number;
+    key: string;
+    value: any;
+} | {
+    ws: boolean;
+    raw: string;
+    start: number;
+    end: number;
+    key: null;
+    value: any;
+})[];
+export function serialize(tokens: any): any;
+export function normalizeQuery(text: any): any;
+export function sameQuery(a: any, b: any): boolean;
+export function effectiveTokens(tokens: any): any;
+export function readToken(text: any, key: any): any;
+export function queryParam(text: any, defaultText: any): {
+    q: string;
+} | null;
+export function reviewRouteQuery(text: any, defaultText: any, page?: null): {} | null;
+export function hasLegacyParams(query: any): boolean;

package/node_modules/@spexcode/spec-core/dist/review/reviewQuery.js

@@ -0,0 +1,180 @@
+// The ONE token-query engine ([[review-query]]) — pure JS, no React/DOM. Both review ListViews, the
+// route layer's legacy replay, and any consumer minting canonical eval/issue addresses import from HERE:
+// the visible query TEXT is the single source of truth, and every tab/menu/autocomplete is only a
+// BUILDER that rewrites tokens in it (GitHub-measured semantics).
+export const ISSUE_QUERY_DEFAULT = 'is:issue state:open';
+export const EVAL_QUERY_DEFAULT = 'is:eval';
+// the session doors' scoped-list address: the default view, scoped — the text shows exactly that.
+export const scopedEvalQuery = (sessionId) => setToken(EVAL_QUERY_DEFAULT, 'scope', sessionId);
+// the aggregate score/count doors' address ([[eval-score-badge]]): the default view, node-filtered.
+export const nodeEvalQuery = (nodeId) => setToken(EVAL_QUERY_DEFAULT, 'node', nodeId);
+const KEY_RE = /^([A-Za-z][A-Za-z0-9-]*):(.*)$/s;
+const unquote = (v) => (v.length >= 2 && v.startsWith('"') && v.endsWith('"') ? v.slice(1, -1) : v);
+export const quoteValue = (v) => (/\s/.test(String(v)) ? `"${v}"` : String(v));
+// segment scan preserving EVERY character — whitespace runs and tokens (a `"` swallows spaces until it
+// closes), each with [start,end) offsets — so the aria-hidden highlight overlay mirrors the input
+// glyph-for-glyph and the autocomplete can find the token under the caret.
+export function scanQuery(text) {
+    const s = String(text ?? '');
+    const out = [];
+    let i = 0;
+    while (i < s.length) {
+        let j = i;
+        if (/\s/.test(s[i])) {
+            while (j < s.length && /\s/.test(s[j]))
+                j++;
+            out.push({ ws: true, raw: s.slice(i, j), start: i, end: j });
+        }
+        else {
+            while (j < s.length && !/\s/.test(s[j])) {
+                if (s[j] === '"') {
+                    j++;
+                    while (j < s.length && s[j] !== '"')
+                        j++;
+                    if (j < s.length)
+                        j++;
+                }
+                else
+                    j++;
+            }
+            const raw = s.slice(i, j);
+            const m = KEY_RE.exec(raw);
+            out.push(m
+                ? { ws: false, raw, start: i, end: j, key: m[1].toLowerCase(), value: unquote(m[2]) }
+                : { ws: false, raw, start: i, end: j, key: null, value: unquote(raw) });
+        }
+        i = j;
+    }
+    return out;
+}
+export const tokenize = (text) => scanQuery(text).filter((seg) => !seg.ws);
+export const serialize = (tokens) => tokens.map((t) => t.raw).join(' ');
+export const normalizeQuery = (text) => serialize(tokenize(text));
+export const sameQuery = (a, b) => normalizeQuery(a) === normalizeQuery(b);
+// duplicate qualifiers: the LAST occurrence wins; bare words all apply.
+export const effectiveTokens = (tokens) => {
+    const last = new Map();
+    for (const t of tokens)
+        if (t.key != null)
+            last.set(t.key, t);
+    return tokens.filter((t) => t.key == null || last.get(t.key) === t);
+};
+export const readToken = (text, key) => {
+    const tokens = tokenize(text);
+    for (let i = tokens.length - 1; i >= 0; i--)
+        if (tokens[i].key === key)
+            return tokens[i].value;
+    return '';
+};
+// token SURGERY: rewrite the key at its first position, drop later duplicates, append when absent,
+// remove the key entirely on an empty value. Every other token — known or not — survives verbatim.
+export function setToken(text, key, value) {
+    const next = value == null || String(value) === ''
+        ? null
+        : { ws: false, raw: `${key}:${quoteValue(value)}`, key, value: String(value) };
+    const out = [];
+    let placed = false;
+    for (const t of tokenize(text)) {
+        if (t.key === key) {
+            if (next && !placed) {
+                out.push(next);
+                placed = true;
+            }
+            continue;
+        }
+        out.push(t);
+    }
+    if (next && !placed)
+        out.push(next);
+    return serialize(out);
+}
+// MATCHING is deliberately NOT here: this module owns text — scan/serialize/surgery/suggestions and the
+// canonical-address discipline — while the conjunctive field matching (including the unknown-qualifier
+// IMPOSSIBLE state) lives in the ONE [[review-filters]] engine, reached through its tokenFilterState
+// bridge. A second predicate here would be the exact fork the fusion removed.
+// canonical address discipline: the default view is the BARE page address; any other state is exactly
+// ?q=<raw text>. An emptied submit falls back to the default (→ bare).
+export const queryParam = (text, defaultText) => {
+    const trimmed = String(text ?? '').trim();
+    if (!trimmed || sameQuery(trimmed, defaultText))
+        return null;
+    return { q: trimmed };
+};
+// A query/filter action resets by omitting page; a PAGINATION action passes a page (including 1) and
+// therefore records GitHub's explicit page=1 history form. The distinction is the action, not equivalence.
+export const reviewRouteQuery = (text, defaultText, page = null) => {
+    const query = queryParam(text, defaultText) || {};
+    if (page != null)
+        query.page = String(page);
+    return Object.keys(query).length ? query : null;
+};
+// LEGACY structured params → token pairs. `kind=all` maps to nothing: the evidence default IS all.
+const LEGACY_PARAMS = {
+    state: (v) => ['state', v],
+    concluded: (v) => (v === '1' ? ['state', 'closed'] : null),
+    ok: (v) => (v === '1' ? ['state', 'reviewed'] : null),
+    verdict: (v) => ['verdict', v],
+    freshness: (v) => ['freshness', v],
+    kind: (v) => (v === 'all' ? null : ['evidence', v]),
+    store: (v) => ['store', v],
+    author: (v) => ['author', v],
+    node: (v) => ['node', v],
+    filer: (v) => ['filer', v],
+    live: (v) => (v === '1' ? ['session', 'present'] : null),
+    session: (v) => ['scope', v],
+};
+export const hasLegacyParams = (query) => Object.keys(LEGACY_PARAMS).some((k) => query?.[k] != null && query[k] !== '');
+// the legacy free q was ONE substring search — it must replay as ONE text token. Quote it whenever the
+// tokenizer would read it as anything else: spaces (several words), a colon (q=drift:check would become
+// an unknown qualifier and match zero), or a stray quote (which would swallow neighbours).
+const freeTextToken = (v) => (/[\s:"]/.test(v) ? `"${v.replace(/"/g, '')}"` : v);
+// a legacy LIST address replays as the FULL visible state: the page's default tokens with each legacy
+// param surgically applied (live=1→session:present, session=<id>→scope:<id>, ok=1→state:reviewed,
+// kind→evidence:), the free-text q appended as ONE bare/phrase token preserving the old
+// single-substring search. Returns null when nothing legacy is present.
+export function legacyQueryText(defaultText, query) {
+    if (!hasLegacyParams(query))
+        return null;
+    let text = defaultText;
+    for (const [param, toPair] of Object.entries(LEGACY_PARAMS)) {
+        const v = query[param];
+        if (v == null || v === '')
+            continue;
+        const pair = toPair(String(v));
+        if (pair)
+            text = setToken(text, pair[0], pair[1]);
+    }
+    const free = String(query.q ?? '').trim();
+    if (free)
+        text = `${text} ${freeTextToken(free)}`.trim();
+    return text;
+}
+// inline autocomplete at the caret — client-side and BOUNDED. A bare prefix completes qualifier KEYS
+// (insert `key:`, keep typing); a `key:prefix` completes VALUES from the page-supplied candidate list
+// only (data-derived; scope = sessions on the current board), capped at 8. Everything else stays
+// hand-typable and submits verbatim.
+export function suggestAt(text, caret, keys = [], values = {}) {
+    const s = String(text ?? '');
+    const at = Math.max(0, Math.min(caret ?? s.length, s.length));
+    const seg = scanQuery(s).find((g) => !g.ws && g.start < at && at <= g.end);
+    if (!seg)
+        return { start: at, end: at, items: [] };
+    const typed = s.slice(seg.start, at);
+    const m = KEY_RE.exec(typed);
+    if (!m) {
+        const w = typed.toLowerCase();
+        if (!w || w.includes('"'))
+            return { start: seg.start, end: seg.end, items: [] };
+        const items = keys.filter((k) => k.startsWith(w)).slice(0, 8)
+            .map((k) => ({ type: 'key', key: k, insert: `${k}:` }));
+        return { start: seg.start, end: seg.end, items };
+    }
+    const key = m[1].toLowerCase();
+    const prefix = m[2].replace(/^"/, '').replace(/"$/, '').toLowerCase();
+    const pool = values[key] || [];
+    const items = pool
+        .filter((c) => String(c.value).toLowerCase().startsWith(prefix) && String(c.value).toLowerCase() !== prefix)
+        .slice(0, 8)
+        .map((c) => ({ type: 'value', key, value: String(c.value), label: c.label || null, insert: `${key}:${quoteValue(c.value)} ` }));
+    return { start: seg.start, end: seg.end, items };
+}

package/node_modules/@spexcode/spec-core/dist/review/session.d.ts

@@ -0,0 +1,4 @@
+export function sessionPresent(sessions: any, id: any): any;
+export function sessionHeadline(session: any): any;
+export function sessionHandle(session: any): any;
+export function sessionTitle(session: any): any;

package/node_modules/@spexcode/spec-core/dist/review/session.js

@@ -0,0 +1,8 @@
+export const sessionPresent = (sessions, id) => {
+    const session = id ? (sessions || []).find((item) => item.id === id) : null;
+    return session || null;
+};
+export const sessionHeadline = (session) => session?.title || session?.headline || session?.name || session?.activity || session?.note
+    || session?.promptPreview || session?.node || session?.raw?.title || session?.branch || session?.id;
+export const sessionHandle = (session) => session?.label || session?.name || session?.node || session?.title || session?.branch || session?.id;
+export const sessionTitle = sessionHeadline;

package/node_modules/@spexcode/spec-core/dist/reviewSnapshot.d.ts

@@ -0,0 +1,15 @@
+export type ReviewEvalNode = {
+    id: string;
+    hue?: number;
+    scenarios: any[];
+    evals: any[];
+    readings: any[];
+};
+export type ReviewSnapshot = {
+    issues: any[];
+    evalNodes: ReviewEvalNode[];
+    forgeRevision: number;
+};
+export declare function publishReviewSnapshot(snapshot: ReviewSnapshot): void;
+export declare function readReviewSnapshot(): ReviewSnapshot;
+export declare function hasReviewSnapshot(): boolean;

package/node_modules/@spexcode/spec-core/dist/reviewSnapshot.js

@@ -0,0 +1,12 @@
+let current = null;
+export function publishReviewSnapshot(snapshot) {
+    current = snapshot;
+}
+export function readReviewSnapshot() {
+    if (!current)
+        throw new Error('review snapshot is unavailable before the first successful graph build');
+    return current;
+}
+export function hasReviewSnapshot() {
+    return current !== null;
+}

package/node_modules/@spexcode/spec-core/dist/root-lru.d.ts

@@ -0,0 +1,4 @@
+export declare const rootSlots: (env: string | undefined, fallback: number) => number;
+export declare function touchRoot(roots: Map<string, string>, cache: Map<string, unknown> & {
+    delete(key: string): boolean;
+}, root: string, key: string, slots: number): void;