@jobshimo/browser-link 0.41.0 → 0.43.0

package/dist/map/learning.d.ts

@@ -0,0 +1,81 @@
+import type Database from 'better-sqlite3';
+/**
+ * The map learns from use.
+ *
+ * Every click/type/press/find/wait_for an agent dispatches already tells us
+ * whether a target worked: a thrown `retargeted`, a `find` that resolved with
+ * `matched: false`, a click whose `expect` was met. Until now that evidence
+ * died with the tool result. This module turns it into ok/fail counters per
+ * durable target in the map DB (`selector_outcomes`, see db.ts), so the
+ * `list_tabs` hint and `browser.map.recall` can say "this selector failed
+ * here before" without the agent doing any bookkeeping.
+ *
+ * Privacy rule: the stored target is the CSS selector string or the
+ * `browser.find` semantic key, and nothing else. Typed text, evaluate
+ * expressions, key names and any other value an action carried are never
+ * read here.
+ *
+ * Two layers:
+ *   - `classifyOutcome` is pure: (tool, args, result, error) → verdict.
+ *   - `recordOutcome` persists one verdict; `learnFromDispatch` is the glue
+ *     the dispatcher's `recordOutcome` dep calls, gated by the config switch.
+ */
+/** The fixed failure vocabulary. `last_reason` never holds anything else. */
+export declare const LEARNED_REASONS: readonly ["retargeted", "ref-stale", "expect-failed", "not-found", "multiple-matches", "unmatched", "timeout", "unsettled", "hit-mismatch"];
+export type LearnedReason = (typeof LEARNED_REASONS)[number];
+export type LearnedOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: LearnedReason;
+};
+export type TargetKind = 'selector' | 'key';
+/** Rows kept per app. Past it, the least used row is evicted. */
+export declare const MAX_LEARNED_PER_APP = 200;
+/**
+ * Classify one dispatched call.
+ *
+ * Returns `{ ok: true }`, `{ ok: false, reason }`, or null when there is
+ * nothing to learn: a tool outside click/type/press/find/wait_for, a call
+ * without a durable target, or a result that proves neither success nor
+ * failure (a quiet click with no `expect`: quiet is not effect).
+ */
+export declare function classifyOutcome(tool: string, args: unknown, result: unknown, error: unknown): LearnedOutcome | null;
+export interface RecordOutcomeInput {
+    origin: string;
+    pathname: string;
+    target: string;
+    target_kind: TargetKind;
+    action: string;
+    outcome: LearnedOutcome;
+}
+/**
+ * Persist one verdict: upsert the counters of the (app, route, target,
+ * kind, action) row, then enforce the per-app cap.
+ *
+ * The app is resolved by `resolveLearnerApp`: the most recently seen app
+ * of the origin (the one `list_tabs` and `recall` show), left untouched,
+ * or a new app keyed by the origin host when the origin has none. The tab
+ * title is never an input: a title such as "Inbox (3) - My App" would mint
+ * a fresh app that then hides the saved map.
+ */
+export declare function recordOutcome(db: Database.Database, input: RecordOutcomeInput): void;
+/** What the dispatcher hands the learner after a call settles. */
+export interface DispatchOutcomeContext {
+    tool: string;
+    args: unknown;
+    result: unknown;
+    error: unknown;
+    /** The tab's URL after the call, from the live tab table. */
+    url: string | null;
+    /** The tab's title. Part of the dispatcher contract but deliberately
+     * ignored by the learner: it never resolves apps from or stores titles. */
+    title: string | null;
+}
+/**
+ * The dispatcher's `recordOutcome` dep in production (wired in server.ts).
+ * Classifies first, so calls with nothing to learn cost no config read and
+ * no DB access; then honours the `mapLearningEnabled` switch, read on every
+ * call so `browser-link config set map-learning off` applies at once.
+ */
+export declare function learnFromDispatch(ctx: DispatchOutcomeContext): void;

package/dist/map/learning.js

@@ -0,0 +1,244 @@
+import { loadConfig } from '../config.js';
+import { getDb } from './db.js';
+import { resolveLearnerApp } from './queries.js';
+/**
+ * The map learns from use.
+ *
+ * Every click/type/press/find/wait_for an agent dispatches already tells us
+ * whether a target worked: a thrown `retargeted`, a `find` that resolved with
+ * `matched: false`, a click whose `expect` was met. Until now that evidence
+ * died with the tool result. This module turns it into ok/fail counters per
+ * durable target in the map DB (`selector_outcomes`, see db.ts), so the
+ * `list_tabs` hint and `browser.map.recall` can say "this selector failed
+ * here before" without the agent doing any bookkeeping.
+ *
+ * Privacy rule: the stored target is the CSS selector string or the
+ * `browser.find` semantic key, and nothing else. Typed text, evaluate
+ * expressions, key names and any other value an action carried are never
+ * read here.
+ *
+ * Two layers:
+ *   - `classifyOutcome` is pure: (tool, args, result, error) → verdict.
+ *   - `recordOutcome` persists one verdict; `learnFromDispatch` is the glue
+ *     the dispatcher's `recordOutcome` dep calls, gated by the config switch.
+ */
+/** The fixed failure vocabulary. `last_reason` never holds anything else. */
+export const LEARNED_REASONS = [
+    'retargeted',
+    'ref-stale',
+    'expect-failed',
+    'not-found',
+    'multiple-matches',
+    'unmatched',
+    'timeout',
+    'unsettled',
+    'hit-mismatch',
+];
+/** Rows kept per app. Past it, the least used row is evicted. */
+export const MAX_LEARNED_PER_APP = 200;
+/** Tools whose outcome says something about a target, and the short action
+ * name stored for them. */
+const LEARNABLE_ACTIONS = {
+    'browser.click': 'click',
+    'browser.type': 'type',
+    'browser.press': 'press',
+    'browser.find': 'find',
+    'browser.wait_for': 'wait_for',
+};
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+/**
+ * The durable target of a call, or null. A selector string counts for every
+ * learnable tool. A semantic key counts only for `browser.find` — on
+ * `browser.press`, `key` is the keyboard key, not an element. A `ref` (or
+ * `find` by text) names no durable target: refs die with the document and
+ * text is a value, so such calls learn nothing.
+ */
+function durableTarget(tool, args) {
+    const a = asRecord(args);
+    if (!a)
+        return null;
+    if (typeof a.selector === 'string' && a.selector.length > 0) {
+        return { target: a.selector, target_kind: 'selector' };
+    }
+    if (tool === 'browser.find') {
+        const key = asRecord(a.key);
+        if (key) {
+            // Fixed field order so the same key always yields the same row.
+            return {
+                target: JSON.stringify({ role: key.role, name: key.name, path: key.path }),
+                target_kind: 'key',
+            };
+        }
+    }
+    return null;
+}
+/** Results normally arrive raw; an MCP `{ content: [{ type: 'text', text }] }`
+ * envelope is read through its first text block. Unparseable text is no
+ * result at all. */
+function unwrapEnvelope(result) {
+    const content = asRecord(result)?.content;
+    if (!Array.isArray(content))
+        return result;
+    const first = asRecord(content[0]);
+    if (first?.type !== 'text' || typeof first.text !== 'string')
+        return null;
+    try {
+        return JSON.parse(first.text);
+    }
+    catch {
+        return null;
+    }
+}
+function errorText(error) {
+    if (error instanceof Error)
+        return error.message;
+    return typeof error === 'string' ? error : String(error);
+}
+/** Thrown failures with a known meaning. Anything else (argument
+ * validation, claim conflicts, a disconnected tab) says nothing about the
+ * target and is not learned. */
+function classifyError(error) {
+    const message = errorText(error);
+    if (/\bretargeted\b|^Click would land on /.test(message)) {
+        return { ok: false, reason: 'retargeted' };
+    }
+    if (/\bref-stale\b/.test(message))
+        return { ok: false, reason: 'ref-stale' };
+    if (/expectation not met/.test(message))
+        return { ok: false, reason: 'expect-failed' };
+    if (/^Tool '.*' timed out after/.test(message))
+        return { ok: false, reason: 'timeout' };
+    if (/^Element not found:/.test(message))
+        return { ok: false, reason: 'not-found' };
+    return null;
+}
+/**
+ * Classify one dispatched call.
+ *
+ * Returns `{ ok: true }`, `{ ok: false, reason }`, or null when there is
+ * nothing to learn: a tool outside click/type/press/find/wait_for, a call
+ * without a durable target, or a result that proves neither success nor
+ * failure (a quiet click with no `expect`: quiet is not effect).
+ */
+export function classifyOutcome(tool, args, result, error) {
+    if (LEARNABLE_ACTIONS[tool] === undefined)
+        return null;
+    const target = durableTarget(tool, args);
+    if (!target)
+        return null;
+    if (error !== undefined)
+        return classifyError(error);
+    const r = asRecord(unwrapEnvelope(result)) ?? {};
+    if (tool === 'browser.find' || tool === 'browser.wait_for') {
+        if (r.matched === true)
+            return { ok: true };
+        if (r.matched !== false)
+            return null;
+        if (tool === 'browser.find' && r.reason === 'not-found') {
+            return { ok: false, reason: 'not-found' };
+        }
+        if (tool === 'browser.find' && r.reason === 'multiple-matches') {
+            return { ok: false, reason: 'multiple-matches' };
+        }
+        return { ok: false, reason: 'unmatched' };
+    }
+    // click / type / press resolved.
+    if (typeof r.hit_element === 'string' &&
+        target.target_kind === 'selector' &&
+        r.hit_element !== target.target) {
+        return { ok: false, reason: 'hit-mismatch' };
+    }
+    // An `expect` that did not hold would have thrown, so a resolved call
+    // carrying one is proof of effect.
+    if (asRecord(args)?.expect !== undefined)
+        return { ok: true };
+    const settle = asRecord(r.settle);
+    if (settle?.settled === false)
+        return { ok: false, reason: 'unsettled' };
+    if (typeof settle?.mutation_count === 'number' && settle.mutation_count > 0) {
+        return { ok: true };
+    }
+    return null;
+}
+/**
+ * Persist one verdict: upsert the counters of the (app, route, target,
+ * kind, action) row, then enforce the per-app cap.
+ *
+ * The app is resolved by `resolveLearnerApp`: the most recently seen app
+ * of the origin (the one `list_tabs` and `recall` show), left untouched,
+ * or a new app keyed by the origin host when the origin has none. The tab
+ * title is never an input: a title such as "Inbox (3) - My App" would mint
+ * a fresh app that then hides the saved map.
+ */
+export function recordOutcome(db, input) {
+    if (!input.outcome.ok && !LEARNED_REASONS.includes(input.outcome.reason))
+        return;
+    const app = resolveLearnerApp(db, input.origin);
+    const ts = new Date().toISOString();
+    const ok = input.outcome.ok;
+    const reason = input.outcome.ok ? null : input.outcome.reason;
+    db.transaction(() => {
+        db.prepare(`INSERT INTO selector_outcomes
+         (app_id, url_pattern, target, target_kind, action, ok_n, fail_n, last_reason, last_ok_at, last_fail_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(app_id, url_pattern, target, target_kind, action) DO UPDATE SET
+         ok_n = ok_n + excluded.ok_n,
+         fail_n = fail_n + excluded.fail_n,
+         last_reason = COALESCE(excluded.last_reason, last_reason),
+         last_ok_at = COALESCE(excluded.last_ok_at, last_ok_at),
+         last_fail_at = COALESCE(excluded.last_fail_at, last_fail_at)`).run(app.id, input.pathname, input.target, input.target_kind, input.action, ok ? 1 : 0, ok ? 0 : 1, reason, ok ? ts : null, ok ? null : ts);
+        const { n } = db
+            .prepare('SELECT COUNT(*) AS n FROM selector_outcomes WHERE app_id = ?')
+            .get(app.id);
+        if (n <= MAX_LEARNED_PER_APP)
+            return;
+        // Evict the least used rows, oldest first on a tie, never the row just
+        // written: evicting the newcomer would freeze a full app forever.
+        db.prepare(`DELETE FROM selector_outcomes WHERE id IN (
+         SELECT id FROM selector_outcomes
+         WHERE app_id = ?
+           AND NOT (url_pattern = ? AND target = ? AND target_kind = ? AND action = ?)
+         ORDER BY ok_n + fail_n ASC,
+                  MAX(COALESCE(last_ok_at, ''), COALESCE(last_fail_at, '')) ASC,
+                  id ASC
+         LIMIT ?
+       )`).run(app.id, input.pathname, input.target, input.target_kind, input.action, n - MAX_LEARNED_PER_APP);
+    })();
+}
+/**
+ * The dispatcher's `recordOutcome` dep in production (wired in server.ts).
+ * Classifies first, so calls with nothing to learn cost no config read and
+ * no DB access; then honours the `mapLearningEnabled` switch, read on every
+ * call so `browser-link config set map-learning off` applies at once.
+ */
+export function learnFromDispatch(ctx) {
+    const outcome = classifyOutcome(ctx.tool, ctx.args, ctx.result, ctx.error);
+    if (!outcome)
+        return;
+    const target = durableTarget(ctx.tool, ctx.args);
+    const action = LEARNABLE_ACTIONS[ctx.tool];
+    if (!target || !action || !ctx.url)
+        return;
+    let url;
+    try {
+        url = new URL(ctx.url);
+    }
+    catch {
+        return;
+    }
+    if (url.origin === 'null')
+        return;
+    if (loadConfig().mapLearningEnabled === false)
+        return;
+    recordOutcome(getDb(), {
+        origin: url.origin,
+        pathname: url.pathname,
+        target: target.target,
+        target_kind: target.target_kind,
+        action,
+        outcome,
+    });
+}
+//# sourceMappingURL=learning.js.map

package/dist/map/learning.js.map

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

package/dist/map/queries.d.ts

@@ -1,3 +1,4 @@
+import type Database from 'better-sqlite3';
 export type EntryKind = 'selector' | 'flow' | 'gotcha';
 export interface AppRow {
     id: number;
@@ -30,6 +31,19 @@ export interface UpsertAppInput {
     notes?: string | null;
 }
 export declare function upsertApp(input: UpsertAppInput): AppRow;
+/**
+ * The app the map learner counts into for an origin, read-only on purpose.
+ *
+ * Picks the most recently seen app of the canonical origin with the same
+ * winner rule `getMapHints` applies (last_seen_at DESC, id DESC), so learned
+ * rows land in the app `list_tabs` and `recall` already show. It never
+ * touches that app's `last_seen_at` or `title`: a passive learner bumping
+ * freshness would reorder which app an origin resolves to. Only when the
+ * origin has no app at all does it create one, keyed and titled by the
+ * origin host, never by a tab title (titles change with page state, e.g.
+ * "Inbox (3) - My App", and would mint a new app per title).
+ */
+export declare function resolveLearnerApp(db: Database.Database, origin: string): AppRow;
 export interface SaveEntryInput {
     origin: string;
     app_key?: string | null;
@@ -84,8 +98,32 @@ export interface RecallResult {
     pitfalls: InsightRow[];
     mechanisms: InsightRow[];
     entries: EntryRow[];
+    /** What the map learned from use (see learning.ts): failures first, then
+     * most used, at most `RECALL_MAX_LEARNED`. Present only when the app has
+     * learned rows, so a recall of an app with none reads exactly as before. */
+    learned?: LearnedRecallItem[];
     flows: FlowRow[];
 }
+/** One learned target as `list_tabs`' inline map carries it. Targets only:
+ * a CSS selector, or a `browser.find` semantic key as JSON. */
+export interface LearnedSummary {
+    target: string;
+    target_kind: 'selector' | 'key';
+    action: string;
+    ok_n: number;
+    fail_n: number;
+    last_reason: string | null;
+}
+/** Recall's richer form: the route it was learned on and when. */
+export interface LearnedRecallItem extends LearnedSummary {
+    url_pattern: string;
+    last_ok_at: string | null;
+    last_fail_at: string | null;
+}
+/** Learned rows of one app in hint order, capped at `limit`. Takes the DB
+ * explicitly so the learner's tests can read through the handle they write
+ * through. */
+export declare function listLearned(db: Database.Database, app_id: number, limit: number): LearnedRecallItem[];
 export declare function recall(input: RecallInput): RecallResult;
 export interface RecordUseInput {
     entry_id: number;
@@ -193,6 +231,10 @@ export interface MapHintInline {
         description: string | null;
         steps: unknown;
     }[];
+    /** Up to 3 learned targets, failures first. Present only when the app has
+     * learned rows and at least one fits the byte cap; never counted toward
+     * `INLINE_MAX_ITEMS`. */
+    learned?: LearnedSummary[];
 }
 export interface MapHint {
     app_key: string;
@@ -203,6 +245,9 @@ export interface MapHint {
     /** Present only when the map is small (see `INLINE_MAX_ITEMS` /
      * `INLINE_MAX_BYTES`); otherwise the counts above are all there is. */
     inline?: MapHintInline;
+    /** Learned targets of this app that have failed at least once, present
+     * only when there are some and no inline map carrying them fits. */
+    learned_failures?: number;
 }
 /**
  * Lean existence-and-count lookup for a tab's origin — powers the optional

package/dist/map/queries.js

@@ -59,6 +59,39 @@ export function upsertApp(input) {
         .run(origin, app_key, input.title ?? null, input.notes ?? null, ts, ts);
     return db.prepare('SELECT * FROM apps WHERE id = ?').get(info.lastInsertRowid);
 }
+/**
+ * The app the map learner counts into for an origin, read-only on purpose.
+ *
+ * Picks the most recently seen app of the canonical origin with the same
+ * winner rule `getMapHints` applies (last_seen_at DESC, id DESC), so learned
+ * rows land in the app `list_tabs` and `recall` already show. It never
+ * touches that app's `last_seen_at` or `title`: a passive learner bumping
+ * freshness would reorder which app an origin resolves to. Only when the
+ * origin has no app at all does it create one, keyed and titled by the
+ * origin host, never by a tab title (titles change with page state, e.g.
+ * "Inbox (3) - My App", and would mint a new app per title).
+ */
+export function resolveLearnerApp(db, origin) {
+    const canonical = canonicalOrigin(origin);
+    const winner = db
+        .prepare('SELECT * FROM apps WHERE origin = ? ORDER BY last_seen_at DESC, id DESC LIMIT 1')
+        .get(canonical);
+    if (winner)
+        return winner;
+    let host;
+    try {
+        host = new URL(canonical).host;
+    }
+    catch {
+        host = canonical;
+    }
+    const ts = now();
+    const info = db
+        .prepare(`INSERT INTO apps (origin, app_key, title, notes, created_at, last_seen_at)
+       VALUES (?, ?, ?, NULL, ?, ?)`)
+        .run(canonical, deriveAppKey(canonical, null), host, ts, ts);
+    return db.prepare('SELECT * FROM apps WHERE id = ?').get(info.lastInsertRowid);
+}
 export function saveEntry(input) {
     const app = upsertApp({
         origin: input.origin,
@@ -131,6 +164,22 @@ export function restoreEntry(input) {
         .get(info.lastInsertRowid);
     return { app, entry: hydrate(inserted) };
 }
+/** At most this many learned rows in a recall. */
+const RECALL_MAX_LEARNED = 50;
+/** At most this many learned rows in the `list_tabs` inline map. */
+const INLINE_MAX_LEARNED = 3;
+/** Failures first (rows that ever failed), then the most used; oldest row
+ * first on a tie so the order is stable. */
+const LEARNED_ORDER = 'ORDER BY (fail_n > 0) DESC, (ok_n + fail_n) DESC, id ASC';
+/** Learned rows of one app in hint order, capped at `limit`. Takes the DB
+ * explicitly so the learner's tests can read through the handle they write
+ * through. */
+export function listLearned(db, app_id, limit) {
+    return db
+        .prepare(`SELECT target, target_kind, action, ok_n, fail_n, last_reason, url_pattern, last_ok_at, last_fail_at
+       FROM selector_outcomes WHERE app_id = ? ${LEARNED_ORDER} LIMIT ?`)
+        .all(app_id, limit);
+}
 export function recall(input) {
     const db = getDb();
     // Same canonicalization as upsertApp — a recall with a trailing-slash or
@@ -162,12 +211,15 @@ export function recall(input) {
             .all(app.id));
     // Flow recipes are not url_pattern-scoped (see the schema comment in
     // db.ts) — recall always returns every flow saved for the app, regardless
-    // of the optional `url` filter.
+    // of the optional `url` filter. Learned rows are app-wide too: each one
+    // carries its own `url_pattern`.
+    const learned = listLearned(db, app.id, RECALL_MAX_LEARNED);
     return {
         app,
         pitfalls: listInsights(app.id, 'pitfall'),
         mechanisms: listInsights(app.id, 'mechanism'),
         entries: rows.map((row) => withPreference(hydrate(row))),
+        ...(learned.length > 0 ? { learned } : {}),
         flows: listFlows(app.id),
     };
 }
@@ -353,6 +405,38 @@ function summarizeInsight(row) {
         ? { key: row.key, description: row.description }
         : { key: row.key, description: row.description, symptom: row.symptom };
 }
+function toLearnedSummary(row) {
+    return {
+        target: row.target,
+        target_kind: row.target_kind,
+        action: row.action,
+        ok_n: row.ok_n,
+        fail_n: row.fail_n,
+        last_reason: row.last_reason,
+    };
+}
+function fitsInline(inline) {
+    return Buffer.byteLength(JSON.stringify(inline), 'utf8') <= INLINE_MAX_BYTES;
+}
+/** The saved map inline (or null when it does not fit), then as many of the
+ * top learned rows as still fit under the same byte cap. With nothing saved,
+ * the inline exists only to carry learned rows: null when none fits. */
+function buildInlineWithLearned(appId, savedTotal) {
+    const base = savedTotal === 0
+        ? { pitfalls: [], mechanisms: [], entries: [], flows: [] }
+        : savedTotal <= INLINE_MAX_ITEMS
+            ? buildInline(appId)
+            : null;
+    if (!base)
+        return null;
+    const learned = listLearned(getDb(), appId, INLINE_MAX_LEARNED).map(toLearnedSummary);
+    for (let n = learned.length; n > 0; n--) {
+        const candidate = { ...base, learned: learned.slice(0, n) };
+        if (fitsInline(candidate))
+            return candidate;
+    }
+    return savedTotal === 0 ? null : base;
+}
 function buildInline(appId) {
     const inline = {
         pitfalls: listInsights(appId, 'pitfall').map(summarizeInsight),
@@ -369,7 +453,7 @@ function buildInline(appId) {
             steps: f.steps,
         })),
     };
-    return Buffer.byteLength(JSON.stringify(inline), 'utf8') <= INLINE_MAX_BYTES ? inline : null;
+    return fitsInline(inline) ? inline : null;
 }
 /**
  * Lean existence-and-count lookup for a tab's origin — powers the optional
@@ -442,7 +526,14 @@ export function getMapHints(origins) {
     const insightCounts = db
         .prepare(`SELECT app_id, kind, COUNT(*) AS n FROM insights WHERE app_id IN (${idPlaceholders}) GROUP BY app_id, kind`)
         .all(...appIds);
+    // What the learner recorded (see learning.ts): total rows and rows that
+    // ever failed, per app, in one more grouped query.
+    const learnedCounts = db
+        .prepare(`SELECT app_id, COUNT(*) AS n, SUM(CASE WHEN fail_n > 0 THEN 1 ELSE 0 END) AS failing
+       FROM selector_outcomes WHERE app_id IN (${idPlaceholders}) GROUP BY app_id`)
+        .all(...appIds);
     const entriesByAppId = new Map(entryCounts.map((row) => [row.app_id, row.n]));
+    const learnedByAppId = new Map(learnedCounts.map((row) => [row.app_id, row]));
     const flowsByAppId = new Map(flowCounts.map((row) => [row.app_id, row.n]));
     const insightCount = (appId, kind) => insightCounts.find((row) => row.app_id === appId && row.kind === kind)?.n ?? 0;
     for (const [origin, app] of winnerByOrigin) {
@@ -451,14 +542,26 @@ export function getMapHints(origins) {
         const mechanisms = insightCount(app.id, 'mechanism');
         const pitfalls = insightCount(app.id, 'pitfall');
         const total = entries + flows + mechanisms + pitfalls;
-        if (total === 0)
+        const learned = learnedByAppId.get(app.id);
+        if (total === 0 && learned === undefined)
             continue;
         const hint = { app_key: app.app_key, entries, flows, mechanisms, pitfalls };
         // Only small maps are expanded (extra queries run just for them), so a
-        // big map costs nothing beyond the count queries above.
-        const inline = total <= INLINE_MAX_ITEMS ? buildInline(app.id) : null;
+        // big map costs nothing beyond the count queries above. Learned rows
+        // never count toward INLINE_MAX_ITEMS; they only share the byte cap.
+        const inline = learned === undefined
+            ? total <= INLINE_MAX_ITEMS
+                ? buildInline(app.id)
+                : null
+            : buildInlineWithLearned(app.id, total);
         if (inline)
             hint.inline = inline;
+        const failing = learned?.failing ?? 0;
+        if (failing > 0 && !inline?.learned)
+            hint.learned_failures = failing;
+        // Learned rows alone that neither fit inline nor ever failed say nothing.
+        if (total === 0 && !hint.inline && hint.learned_failures === undefined)
+            continue;
         result.set(origin, hint);
     }
     return result;