@hotmeshio/long-tail 0.31.1 → 0.32.0

package/build/shared/form-validation/x-lt-confidence-facets.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Review facets: a few low-cardinality metadata keys summarizing how a
+ * reviewer treated a model's proposals, stamped onto the row in the same
+ * guarded UPDATE that resolves it. Opt in on the schema root with
+ * `"x-lt-confidence": { "facets": true }`. Counts cover the fields the form
+ * shows for the submitted answer, the same set the legend counts. Values are
+ * strings so `metadata @>` filters and analytics projections match exactly.
+ */
+import { type ShowIfContext } from './x-lt-show-if';
+export declare const REVIEW_FACET_KEYS: {
+    readonly OUTCOME: "review_outcome";
+    readonly CHANGED: "review_changed";
+    readonly WORST: "review_worst";
+};
+export declare const REVIEW_OUTCOMES: {
+    readonly ACCEPTED: "accepted";
+    readonly CORRECTED: "corrected";
+};
+export type ReviewFacets = Partial<Record<(typeof REVIEW_FACET_KEYS)[keyof typeof REVIEW_FACET_KEYS], string>>;
+/** The fields the form shows for these values: x-lt-hidden, x-lt-showIf and x-lt-hide-if-empty applied. */
+export declare function visibleFieldKeys(formSchema: Record<string, unknown>, formValues: Record<string, unknown>, ctx: ShowIfContext): string[];
+/**
+ * The review facets for a submitted answer, or null when the schema does not
+ * opt in or no shown field carries a proposal or score. `review_worst` is the
+ * lowest tranche any shown field fell into, absent when every score cleared.
+ */
+export declare function buildReviewFacets(formSchema: Record<string, unknown> | null | undefined, ctx: ShowIfContext | null | undefined, formValues: Record<string, unknown>): ReviewFacets | null;

package/build/shared/form-validation/x-lt-confidence-facets.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVIEW_OUTCOMES = exports.REVIEW_FACET_KEYS = void 0;
+exports.visibleFieldKeys = visibleFieldKeys;
+exports.buildReviewFacets = buildReviewFacets;
+/**
+ * Review facets: a few low-cardinality metadata keys summarizing how a
+ * reviewer treated a model's proposals, stamped onto the row in the same
+ * guarded UPDATE that resolves it. Opt in on the schema root with
+ * `"x-lt-confidence": { "facets": true }`. Counts cover the fields the form
+ * shows for the submitted answer, the same set the legend counts. Values are
+ * strings so `metadata @>` filters and analytics projections match exactly.
+ */
+const x_lt_show_if_1 = require("./x-lt-show-if");
+const x_lt_confidence_1 = require("./x-lt-confidence");
+exports.REVIEW_FACET_KEYS = {
+    OUTCOME: 'review_outcome',
+    CHANGED: 'review_changed',
+    WORST: 'review_worst',
+};
+exports.REVIEW_OUTCOMES = {
+    ACCEPTED: 'accepted',
+    CORRECTED: 'corrected',
+};
+/** The fields the form shows for these values: x-lt-hidden, x-lt-showIf and x-lt-hide-if-empty applied. */
+function visibleFieldKeys(formSchema, formValues, ctx) {
+    const props = (formSchema.properties ?? {});
+    return Object.keys(props).filter((key) => {
+        const def = props[key];
+        if ((0, x_lt_show_if_1.isHiddenField)(def))
+            return false;
+        if (!(0, x_lt_show_if_1.evaluateShowIf)(def?.['x-lt-showIf'], ctx))
+            return false;
+        return !(0, x_lt_show_if_1.isHiddenIfEmpty)(def, formValues[key]);
+    });
+}
+/**
+ * The review facets for a submitted answer, or null when the schema does not
+ * opt in or no shown field carries a proposal or score. `review_worst` is the
+ * lowest tranche any shown field fell into, absent when every score cleared.
+ */
+function buildReviewFacets(formSchema, ctx, formValues) {
+    if (!formSchema)
+        return null;
+    const spec = (0, x_lt_confidence_1.readConfidenceSpec)(formSchema);
+    if (!spec?.facets)
+        return null;
+    const liveCtx = { ...(ctx ?? {}), resolver: formValues, input: formValues };
+    const review = (0, x_lt_confidence_1.buildFormReview)(spec, formSchema, liveCtx, formValues);
+    const shown = visibleFieldKeys(formSchema, formValues, liveCtx).filter((key) => review[key]);
+    if (shown.length === 0)
+        return null;
+    const summary = (0, x_lt_confidence_1.summarizeReview)(spec, review, shown);
+    const worst = summary.tranches.find((t) => t.fields.length > 0)?.tranche;
+    return {
+        [exports.REVIEW_FACET_KEYS.OUTCOME]: summary.changed.length > 0 ? exports.REVIEW_OUTCOMES.CORRECTED : exports.REVIEW_OUTCOMES.ACCEPTED,
+        [exports.REVIEW_FACET_KEYS.CHANGED]: String(summary.changed.length),
+        ...(worst ? { [exports.REVIEW_FACET_KEYS.WORST]: worst.label } : {}),
+    };
+}

package/build/shared/form-validation/x-lt-confidence.d.ts

@@ -0,0 +1,57 @@
+export declare const CONFIDENCE_TONES: {
+    readonly ERROR: "error";
+    readonly WARNING: "warning";
+    readonly INFO: "info";
+};
+export type ConfidenceTone = (typeof CONFIDENCE_TONES)[keyof typeof CONFIDENCE_TONES];
+export interface ConfidenceTranche {
+    below: number;
+    label: string;
+    tone: ConfidenceTone;
+}
+export interface ConfidenceSpec {
+    scores: string;
+    proposed: string;
+    tranches: ConfidenceTranche[];
+    /** Stamp the review summary onto the row's metadata at resolve. */
+    facets: boolean;
+}
+export declare const CONFIDENCE_SCORES_PATH = "envelope.confidence";
+export declare const CONFIDENCE_PROPOSED_PATH = "envelope.formDefaults";
+export declare const DEFAULT_CONFIDENCE_TRANCHES: readonly ConfidenceTranche[];
+/** The schema's confidence declaration, or null when the form declares none. */
+export declare function readConfidenceSpec(schema: Record<string, unknown> | null | undefined): ConfidenceSpec | null;
+/** The tranche a score falls into, or null when the score clears every threshold. */
+export declare function trancheFor(tranches: readonly ConfidenceTranche[], score: number): ConfidenceTranche | null;
+/** Whether an answer differs from what was proposed for it. */
+export declare function differsFromProposal(proposed: unknown, current: unknown): boolean;
+export interface FieldReview {
+    /** The field's score in [0, 1], when the workflow scored it. */
+    score?: number;
+    /** The tranche the score falls into; absent when confident or unscored. */
+    tranche?: ConfidenceTranche;
+    /** Whether the workflow proposed a value for the field. */
+    hasProposal: boolean;
+    /** The proposed value, in form shape. */
+    proposed?: unknown;
+    /** Whether the current answer differs from the proposal. */
+    changed: boolean;
+}
+/**
+ * The review state of every field the spec covers: its score and tranche,
+ * its proposal, and whether `values` (the live form, or a submitted payload
+ * mapped back to form shape) differs from it. Proposals and scores are read
+ * in payload shape and mapped through x-lt-bind, like formDefaults.
+ */
+export declare function buildFormReview(spec: ConfidenceSpec, formSchema: Record<string, unknown>, ctx: Record<string, unknown> | undefined, values: Record<string, unknown>): Record<string, FieldReview>;
+export interface ReviewSummary {
+    /** Field keys per tranche label, in tranche order. */
+    tranches: Array<{
+        tranche: ConfidenceTranche;
+        fields: string[];
+    }>;
+    /** Field keys whose answer differs from the proposal. */
+    changed: string[];
+}
+/** Counts for the form's legend, over the fields actually shown, in their order. */
+export declare function summarizeReview(spec: ConfidenceSpec, review: Record<string, FieldReview>, shownKeys: readonly string[]): ReviewSummary;

package/build/shared/form-validation/x-lt-confidence.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CONFIDENCE_TRANCHES = exports.CONFIDENCE_PROPOSED_PATH = exports.CONFIDENCE_SCORES_PATH = exports.CONFIDENCE_TONES = void 0;
+exports.readConfidenceSpec = readConfidenceSpec;
+exports.trancheFor = trancheFor;
+exports.differsFromProposal = differsFromProposal;
+exports.buildFormReview = buildFormReview;
+exports.summarizeReview = summarizeReview;
+/**
+ * x-lt-confidence: review state for a form a model filled in. The workflow
+ * proposes values (`envelope.formDefaults`) and scores them
+ * (`envelope.confidence`, the same shape, numbers in [0, 1]); the schema root
+ * declares the tranches a score falls into:
+ *
+ *   "x-lt-confidence": {
+ *     "tranches": [
+ *       { "below": 0.6, "label": "Low",   "tone": "error" },
+ *       { "below": 0.9, "label": "Check", "tone": "warning" }
+ *     ]
+ *   }
+ *
+ * A score falls into the first tranche whose `below` it is under; a score at
+ * or above every threshold is confident and carries no tranche. Every field
+ * with a proposal also reports whether the answer differs from it, so the
+ * form shows what a value was and what it became, before and after submit.
+ * `scores` and `proposed` name other context paths when the workflow keeps
+ * them elsewhere. `"facets": true` stamps a review summary onto the row's
+ * metadata when it resolves (see x-lt-confidence-facets). A field opts out
+ * with `"x-lt-confidence": false`. Pure: the dashboard renders with it, and
+ * workflows and agents can diff with it.
+ */
+const ctx_path_1 = require("./ctx-path");
+const display_only_widgets_1 = require("./display-only-widgets");
+const x_lt_bind_1 = require("./x-lt-bind");
+exports.CONFIDENCE_TONES = {
+    ERROR: 'error',
+    WARNING: 'warning',
+    INFO: 'info',
+};
+exports.CONFIDENCE_SCORES_PATH = 'envelope.confidence';
+exports.CONFIDENCE_PROPOSED_PATH = 'envelope.formDefaults';
+exports.DEFAULT_CONFIDENCE_TRANCHES = [
+    { below: 0.6, label: 'Low', tone: exports.CONFIDENCE_TONES.ERROR },
+    { below: 0.85, label: 'Check', tone: exports.CONFIDENCE_TONES.WARNING },
+];
+const TONES = new Set(Object.values(exports.CONFIDENCE_TONES));
+function readTranches(raw) {
+    if (!Array.isArray(raw))
+        return [...exports.DEFAULT_CONFIDENCE_TRANCHES];
+    const byThreshold = new Map();
+    for (const entry of raw) {
+        const t = (entry ?? {});
+        if (typeof t.below !== 'number' || !Number.isFinite(t.below) || t.below <= 0 || t.below > 1)
+            continue;
+        if (typeof t.label !== 'string' || t.label.trim().length === 0)
+            continue;
+        const tone = typeof t.tone === 'string' && TONES.has(t.tone) ? t.tone : exports.CONFIDENCE_TONES.WARNING;
+        if (!byThreshold.has(t.below))
+            byThreshold.set(t.below, { below: t.below, label: t.label.trim(), tone });
+    }
+    return [...byThreshold.values()].sort((a, b) => a.below - b.below);
+}
+/** The schema's confidence declaration, or null when the form declares none. */
+function readConfidenceSpec(schema) {
+    const raw = schema?.['x-lt-confidence'];
+    if (raw === true) {
+        return {
+            scores: exports.CONFIDENCE_SCORES_PATH,
+            proposed: exports.CONFIDENCE_PROPOSED_PATH,
+            tranches: [...exports.DEFAULT_CONFIDENCE_TRANCHES],
+            facets: false,
+        };
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const spec = raw;
+    return {
+        scores: typeof spec.scores === 'string' && spec.scores ? spec.scores : exports.CONFIDENCE_SCORES_PATH,
+        proposed: typeof spec.proposed === 'string' && spec.proposed ? spec.proposed : exports.CONFIDENCE_PROPOSED_PATH,
+        tranches: readTranches(spec.tranches),
+        facets: spec.facets === true,
+    };
+}
+/** The tranche a score falls into, or null when the score clears every threshold. */
+function trancheFor(tranches, score) {
+    for (const tranche of tranches) {
+        if (score < tranche.below)
+            return tranche;
+    }
+    return null;
+}
+/** Text compared by its words: surrounding and repeated whitespace is not a change. */
+function normalizeText(value) {
+    return value.trim().replace(/\s+/g, ' ');
+}
+function stableJson(value) {
+    if (typeof value === 'string')
+        return JSON.stringify(normalizeText(value));
+    if (Array.isArray(value))
+        return `[${value.map(stableJson).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const entries = Object.keys(value).sort()
+            .map((k) => `${JSON.stringify(k)}:${stableJson(value[k])}`);
+        return `{${entries.join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+/**
+ * A value's comparable form: empty answers compare equal, "42" equals 42,
+ * whitespace-only edits are not changes, and key order is ignored.
+ */
+function comparable(value) {
+    if (value === null || value === undefined)
+        return '';
+    if (typeof value === 'object')
+        return stableJson(value);
+    return normalizeText(String(value));
+}
+/** Whether an answer differs from what was proposed for it. */
+function differsFromProposal(proposed, current) {
+    return comparable(proposed) !== comparable(current);
+}
+function asFormMap(source, formSchema) {
+    if (!source || typeof source !== 'object' || Array.isArray(source))
+        return {};
+    try {
+        return (0, x_lt_bind_1.mapPayloadToForm)(source, formSchema);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * The review state of every field the spec covers: its score and tranche,
+ * its proposal, and whether `values` (the live form, or a submitted payload
+ * mapped back to form shape) differs from it. Proposals and scores are read
+ * in payload shape and mapped through x-lt-bind, like formDefaults.
+ */
+function buildFormReview(spec, formSchema, ctx, values) {
+    const props = (formSchema.properties ?? {});
+    const scores = asFormMap((0, ctx_path_1.resolveCtxPath)(spec.scores, ctx), formSchema);
+    const proposals = asFormMap((0, ctx_path_1.resolveCtxPath)(spec.proposed, ctx), formSchema);
+    const review = {};
+    for (const [key, def] of Object.entries(props)) {
+        if (def?.['x-lt-confidence'] === false || (0, display_only_widgets_1.isDisplayOnlyField)(def))
+            continue;
+        const raw = scores[key];
+        const score = typeof raw === 'number' && Number.isFinite(raw) ? Math.min(Math.max(raw, 0), 1) : undefined;
+        const hasProposal = key in proposals;
+        if (score === undefined && !hasProposal)
+            continue;
+        const tranche = score === undefined ? null : trancheFor(spec.tranches, score);
+        review[key] = {
+            ...(score !== undefined ? { score } : {}),
+            ...(tranche ? { tranche } : {}),
+            hasProposal,
+            ...(hasProposal ? { proposed: proposals[key] } : {}),
+            changed: hasProposal && differsFromProposal(proposals[key], values[key]),
+        };
+    }
+    return review;
+}
+/** Counts for the form's legend, over the fields actually shown, in their order. */
+function summarizeReview(spec, review, shownKeys) {
+    const tranches = spec.tranches.map((tranche) => ({ tranche, fields: [] }));
+    const changed = [];
+    for (const key of shownKeys) {
+        const field = review[key];
+        if (!field)
+            continue;
+        if (field.tranche)
+            tranches.find((t) => t.tranche.below === field.tranche.below)?.fields.push(key);
+        if (field.changed)
+            changed.push(key);
+    }
+    return { tranches, changed };
+}

package/build/shared/form-validation/x-lt-help.d.ts

@@ -1,5 +1,5 @@
 /** The token domains a help template may reference. `input` is the invoke-form name for the live values `resolver` also carries. */
-export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver", "lookup", "input", "roster"];
+export declare const HELP_DOMAINS: readonly ["escalation", "metadata", "envelope", "payload", "resolver", "lookup", "input", "roster", "file"];
 export type HelpDomain = (typeof HELP_DOMAINS)[number];
 export type HelpTokenContext = Partial<Record<HelpDomain, Record<string, unknown> | null>>;
 /** Replace every `{{domain.path}}` token with its value from the context. */

package/build/shared/form-validation/x-lt-help.js

@@ -25,7 +25,7 @@ exports.defaultHelpMarkdown = defaultHelpMarkdown;
  */
 const x_lt_bind_1 = require("./x-lt-bind");
 /** The token domains a help template may reference. `input` is the invoke-form name for the live values `resolver` also carries. */
-exports.HELP_DOMAINS = ['escalation', 'metadata', 'envelope', 'payload', 'resolver', 'lookup', 'input', 'roster'];
+exports.HELP_DOMAINS = ['escalation', 'metadata', 'envelope', 'payload', 'resolver', 'lookup', 'input', 'roster', 'file'];
 const TOKEN_PATTERN = /\{\{\s*([^{}]+?)\s*\}\}/g;
 const MISSING_VALUE = '—';
 function formatTokenValue(value) {

package/build/system/mcp-servers/admin/escalations.js

@@ -308,9 +308,11 @@ function registerEscalationTools(server) {
     server.registerTool('aggregate_by_facets', {
         title: 'Aggregate by Facets',
         description: 'Grouped analytics over the escalation intervals. Every escalation is one open ' +
-            'interval [created_at, ended_at); this tool reads it two ways: membership (rows or, ' +
+            'interval [created_at, ended_at); this tool reads it three ways: membership (rows or, ' +
             'with distinctBy, distinct entities open at an instant — a past asOf reconstructs the ' +
-            'live set then) and dwell (open-seconds per group within a half-open [from,to) window). ' +
+            'live set then), dwell (open-seconds per group within a half-open [from,to) window), and ' +
+            'resolved (rows resolved within a window, optionally per day/week/month bucket: trends ' +
+            'such as weekly review outcomes by extractor; needs a role scope). ' +
             'Group by role/subtype/status columns plus metadata facet keys; optional states[] label ' +
             'each group. One call replaces N per-filter count round-trips. The filter takes the WHAT ' +
             'fields only — status/available/jeopardy are rejected (liveness derives from the measure).',

package/build/system/mcp-servers/admin/labels-schemas.d.ts

@@ -16,12 +16,12 @@ export declare const upsertLabelTemplateSchema: z.ZodObject<{
         caption: z.ZodOptional<z.ZodString>;
         tone: z.ZodEnum<["solid", "outline", "plain"]>;
     }, "strip", z.ZodTypeAny, {
-        category: string;
         tone: "solid" | "outline" | "plain";
+        category: string;
         caption?: string | undefined;
     }, {
-        category: string;
         tone: "solid" | "outline" | "plain";
+        category: string;
         caption?: string | undefined;
     }>, "many">;
     text: z.ZodOptional<z.ZodObject<{
@@ -45,8 +45,8 @@ export declare const upsertLabelTemplateSchema: z.ZodObject<{
     scheme_version: number;
     title: string;
     codes: {
-        category: string;
         tone: "solid" | "outline" | "plain";
+        category: string;
         caption?: string | undefined;
     }[];
     enabled?: boolean | undefined;
@@ -65,8 +65,8 @@ export declare const upsertLabelTemplateSchema: z.ZodObject<{
     scheme_version: number;
     title: string;
     codes: {
-        category: string;
         tone: "solid" | "outline" | "plain";
+        category: string;
         caption?: string | undefined;
     }[];
     enabled?: boolean | undefined;