@pellux/goodvibes-tui 0.25.0 → 0.27.0

package/src/daemon/{channels → handlers}/routing/route-store.ts

@@ -1,13 +1,13 @@
 import { randomUUID } from 'node:crypto';
-import { OperatorSqliteStore } from '../../operator/sqlite-store.ts';
-import { OperatorError } from '../../operator/types.ts';
+import { HandlerSqliteStore } from '../sqlite-store.ts';
+import { HandlerError } from '../errors.ts';
 
 /**
  * A persisted channel-to-profile routing assignment, in the exact shape the
- * `channels.routing.*` operator methods return (see daemon handoff doc,
- * Responsibility 2). This is intentionally distinct from the foundation's
- * generic `ChannelRoute` type — the routing control-plane has its own contract
- * keyed on (surfaceKind, routeId) composite channel IDs.
+ * `channels.routing.*` methods serve. Keyed on a composite `channelId`
+ * (`surfaceKind` or `surfaceKind:routeId`). The SDK output schemas require
+ * `surfaceKind`, `profileId`, `createdAt`, and `updatedAt`; `channelId`,
+ * `routeId`, and `label` are carried through as optional refinements.
  */
 export interface RoutingChannelRoute {
   assignmentId: string;
@@ -21,6 +21,47 @@ export interface RoutingChannelRoute {
   updatedAt: string; // ISO-8601
 }
 
+/**
+ * Per-route item shape emitted by `channels.routing.list`, matching the SDK
+ * `CHANNEL_ROUTING_RULE_SCHEMA` exactly: properties
+ * {id, createdAt, updatedAt, surfaceKind, routeId, profileId, label},
+ * required [id, createdAt, updatedAt, surfaceKind, profileId], and
+ * additionalProperties:false. The store's `assignmentId` is projected to `id`,
+ * and the daemon-internal `channelId` is dropped (it is forbidden by the
+ * schema's additionalProperties:false).
+ */
+export interface RoutingRouteListItem {
+  id: string;
+  createdAt: string; // ISO-8601
+  updatedAt: string; // ISO-8601
+  surfaceKind: string;
+  routeId?: string;
+  profileId: string;
+  label?: string;
+}
+
+/**
+ * Project a stored route to the SDK `channels.routing.list` item shape. Pure;
+ * only includes optional `routeId`/`label` when present so the payload never
+ * carries `undefined`-valued or schema-forbidden keys.
+ */
+export function toRouteListItem(route: RoutingChannelRoute): RoutingRouteListItem {
+  const item: RoutingRouteListItem = {
+    id: route.assignmentId,
+    createdAt: route.createdAt,
+    updatedAt: route.updatedAt,
+    surfaceKind: route.surfaceKind,
+    profileId: route.profileId,
+  };
+  if (route.routeId !== undefined) {
+    item.routeId = route.routeId;
+  }
+  if (route.label !== undefined) {
+    item.label = route.label;
+  }
+  return item;
+}
+
 /** Parsed components of a composite channelId. */
 export interface ParsedChannelId {
   surfaceKind: string;
@@ -80,7 +121,7 @@ interface RouteRow {
 export function parseChannelId(channelId: string): ParsedChannelId {
   const raw = typeof channelId === 'string' ? channelId.trim() : '';
   if (raw.length === 0) {
-    throw new OperatorError('channelId is required', 'ROUTING_INVALID_CHANNEL_ID', 400);
+    throw new HandlerError('channelId is required', 'ROUTING_INVALID_CHANNEL_ID', 400);
   }
   const separator = raw.indexOf(':');
   if (separator === -1) {
@@ -89,7 +130,7 @@ export function parseChannelId(channelId: string): ParsedChannelId {
   const surfaceKind = raw.slice(0, separator).trim();
   const routeId = raw.slice(separator + 1).trim();
   if (surfaceKind.length === 0) {
-    throw new OperatorError('channelId is missing a surfaceKind', 'ROUTING_INVALID_CHANNEL_ID', 400);
+    throw new HandlerError('channelId is missing a surfaceKind', 'ROUTING_INVALID_CHANNEL_ID', 400);
   }
   // A trailing colon with no routeId collapses to a surface-only assignment.
   return routeId.length === 0 ? { surfaceKind } : { surfaceKind, routeId };
@@ -117,16 +158,16 @@ function rowToRoute(row: RouteRow): RoutingChannelRoute {
 /**
  * SQLite-backed store for channel-to-profile routing assignments.
  *
- * Wraps {@link OperatorSqliteStore} (file `channel-routes.sqlite`) and persists
+ * Wraps {@link HandlerSqliteStore} (file `channel-routes.sqlite`) and persists
  * after every mutation. The store owns the composite-key parsing so callers only
  * ever deal with `channelId` strings.
  */
 export class RouteStore {
-  private readonly store: OperatorSqliteStore;
+  private readonly store: HandlerSqliteStore;
   private initialized = false;
 
   constructor(options: { workingDirectory: string }) {
-    this.store = new OperatorSqliteStore({
+    this.store = new HandlerSqliteStore({
       workingDirectory: options.workingDirectory,
       fileName: 'channel-routes.sqlite',
       schema: SCHEMA,
@@ -150,7 +191,7 @@ export class RouteStore {
 
   private requireInit(): void {
     if (!this.initialized) {
-      throw new OperatorError('RouteStore not initialized', 'ROUTING_STORE_UNINITIALIZED', 500);
+      throw new HandlerError('RouteStore not initialized', 'ROUTING_STORE_UNINITIALIZED', 500);
     }
   }
 
@@ -219,7 +260,7 @@ export class RouteStore {
     this.requireInit();
     const profileId = typeof input.profileId === 'string' ? input.profileId.trim() : '';
     if (profileId.length === 0) {
-      throw new OperatorError('profileId is required', 'ROUTING_INVALID_PROFILE_ID', 400);
+      throw new HandlerError('profileId is required', 'ROUTING_INVALID_PROFILE_ID', 400);
     }
     const { surfaceKind, routeId } = parseChannelId(input.channelId);
     const channelId = buildChannelId(surfaceKind, routeId);
@@ -239,7 +280,7 @@ export class RouteStore {
       await this.store.save();
       const route = this.findById(existing.assignmentId);
       if (!route) {
-        throw new OperatorError('Failed to read back updated route', 'ROUTING_WRITE_FAILED', 500);
+        throw new HandlerError('Failed to read back updated route', 'ROUTING_WRITE_FAILED', 500);
       }
       return { route, created: false };
     }
@@ -254,7 +295,7 @@ export class RouteStore {
     await this.store.save();
     const route = this.findById(assignmentId);
     if (!route) {
-      throw new OperatorError('Failed to read back inserted route', 'ROUTING_WRITE_FAILED', 500);
+      throw new HandlerError('Failed to read back inserted route', 'ROUTING_WRITE_FAILED', 500);
     }
     return { route, created: true };
   }
@@ -267,7 +308,7 @@ export class RouteStore {
     this.requireInit();
     const id = typeof assignmentId === 'string' ? assignmentId.trim() : '';
     if (id.length === 0) {
-      throw new OperatorError('assignmentId is required', 'ROUTING_INVALID_ASSIGNMENT_ID', 400);
+      throw new HandlerError('assignmentId is required', 'ROUTING_INVALID_ASSIGNMENT_ID', 400);
     }
     const existing = this.findById(id);
     if (!existing) return false;

package/src/daemon/{channels → handlers}/routing/routing-resolver.ts

@@ -1,5 +1,5 @@
 import type { RoutingChannelRoute } from './route-store.ts';
-import { RouteStore } from './route-store.ts';
+import type { RouteStore } from './route-store.ts';
 
 /** Wildcard surfaceKind that matches any surface as a last resort. */
 export const WILDCARD_SURFACE = 'any';

package/src/daemon/{operator → handlers}/sqlite-store.ts

@@ -7,7 +7,7 @@ import initSqlJs from 'sql.js';
 type SqlJsStatic = Awaited<ReturnType<typeof initSqlJs>>;
 type SqlDatabase = InstanceType<SqlJsStatic['Database']>;
 
-export interface OperatorSqliteOptions {
+export interface SqliteStoreOptions {
   workingDirectory: string;
   /** e.g. 'channel-routes.sqlite', 'drafts.sqlite', 'inbox-cursors.sqlite' */
   fileName: string;
@@ -29,12 +29,12 @@ async function loadSqlJs(): Promise<SqlJsStatic> {
  * (sql.js WASM: init → run/exec → save → close). One file per concern under
  * {workingDirectory}/.goodvibes/tui/operator/{fileName}.
  */
-export class OperatorSqliteStore {
-  private readonly options: OperatorSqliteOptions;
+export class HandlerSqliteStore {
+  private readonly options: SqliteStoreOptions;
   private readonly resolvedPath: string;
   private db: SqlDatabase | null = null;
 
-  constructor(options: OperatorSqliteOptions) {
+  constructor(options: SqliteStoreOptions) {
     this.options = options;
     this.resolvedPath = join(
       options.workingDirectory,
@@ -51,7 +51,7 @@ export class OperatorSqliteStore {
 
   private requireDb(): SqlDatabase {
     if (!this.db) {
-      throw new Error(`OperatorSqliteStore not initialized: ${this.resolvedPath}`);
+      throw new Error(`HandlerSqliteStore not initialized: ${this.resolvedPath}`);
     }
     return this.db;
   }

package/src/daemon/handlers/triage/index.ts

@@ -0,0 +1,57 @@
+// ---------------------------------------------------------------------------
+// Public surface for the daemon-internal Email Auto-Tag / Spam Triage handler.
+//
+// `registerTriagedInbox` (from ./integration.ts) is the single entry the
+// runtime composition root calls. It DECORATES the inbox surface's
+// `channels.inbox.list` handler (overlaying persisted triage metadata) and
+// returns the poller-facing pipeline + tagger. inbox.triage.* are NOT published
+// catalog methods — this surface registers no triage method id.
+// ---------------------------------------------------------------------------
+
+export {
+  scoreInboundItem,
+  labelToTag,
+  type TriageScore,
+  type TriageScorerOptions,
+} from './scorer.ts';
+
+export type {
+  InboundChannelItem,
+  TriageLabel,
+  ConversationKind,
+} from './types.ts';
+
+export {
+  runInboxTriage,
+  createTriageStore,
+  readTriageMetadata,
+  readTriageMetadataBatch,
+  enrichItemsWithTriage,
+  TRIAGE_STORE_FILE,
+  type TriageMetadata,
+  type TriagedItem,
+  type TriageOverlay,
+  type TriageEnrichedItem,
+  type RunInboxTriageOptions,
+  type RunInboxTriageResult,
+} from './pipeline.ts';
+
+export {
+  createTriageTagger,
+  TRIAGE_AUTOTAG_FLAG,
+  type TriageTagger,
+  type TriageTaggerOptions,
+  type TaggerProviderConfig,
+  type ApplyTagsRequest,
+  type ApplyTagsResult,
+  type ImapStoreArgs,
+  type ImapRetryOptions,
+} from './tagger/index.ts';
+
+export {
+  registerTriagedInbox,
+  INBOX_LIST_METHOD_ID,
+  type RegisterInbox,
+  type RegisterTriagedInboxOptions,
+  type TriagedInboxRegistration,
+} from './integration.ts';

package/src/daemon/handlers/triage/integration.ts

@@ -0,0 +1,213 @@
+// ---------------------------------------------------------------------------
+// Daemon-internal triage INTEGRATION (the single entry the runtime calls).
+//
+// `registerTriagedInbox(ctx, registerInbox, options)` closes the contract loop:
+//
+//   1. It DECORATES the inbox surface's `channels.inbox.list` handler. The
+//      inbox surface (a separate handler module) attaches its handler to the
+//      SDK-auto-registered descriptor via `ctx.catalog.register(descriptor,
+//      handler, { replace: true })`. We pass the inbox `registerInbox` a
+//      catalog PROXY whose `register` intercepts exactly the
+//      `channels.inbox.list` id and wraps the handler so every returned item is
+//      overlaid with the persisted triageScore/triageTags via
+//      enrichItemsWithTriage(). Every other registration passes straight
+//      through to the real catalog. The inbox descriptor/schema/id is never
+//      re-authored — only its handler is wrapped.
+//   2. It exposes the triage pipeline + tagger (`runInboxTriage`, `tagger`) for
+//      the daemon-internal poller, which scores items and persists them to the
+//      co-located inbox-triage.sqlite store the decorator reads from.
+//   3. inbox.triage.* are intentionally NOT registered on the catalog (they are
+//      a daemon-internal pipeline, not published methods) — so this module
+//      makes ZERO catalog.register call for any triage id.
+//
+// Reads in the decorator are best-effort and degrade to the raw item when no
+// triage row exists yet, so the read-only inbox feed never breaks.
+// ---------------------------------------------------------------------------
+
+import type { HandlerContext } from '../context.ts';
+import type {
+  GatewayMethodCatalog,
+  GatewayMethodDescriptor,
+  GatewayMethodHandler,
+} from '../contracts.ts';
+import type { Unregister } from '../register.ts';
+import { HandlerSqliteStore } from '../sqlite-store.ts';
+import {
+  createTriageStore,
+  enrichItemsWithTriage,
+  runInboxTriage,
+  type RunInboxTriageOptions,
+  type RunInboxTriageResult,
+} from './pipeline.ts';
+import type { InboundChannelItem } from './types.ts';
+import {
+  createTriageTagger,
+  type ApplyTagsRequest,
+  type ApplyTagsResult,
+  type TriageTagger,
+  type TriageTaggerOptions,
+} from './tagger/index.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
+
+/**
+ * Canonical id of the inbox list method whose handler we decorate. This is the
+ * SDK's published id — referenced as a plain string for matching during
+ * registration; no descriptor or schema is authored here.
+ */
+export const INBOX_LIST_METHOD_ID = 'channels.inbox.list';
+
+/** Minimal shape of the inbox.list result the decorator overlays triage onto. */
+interface InboxListResult {
+  items?: unknown;
+  [key: string]: unknown;
+}
+
+export interface RegisterTriagedInboxOptions {
+  pipeline?: RunInboxTriageOptions;
+  tagger?: TriageTaggerOptions;
+}
+
+/**
+ * The inbox surface provider. The runtime supplies the inbox module's register
+ * function; we hand it a decorating catalog proxy so its `channels.inbox.list`
+ * handler is wrapped with triage enrichment.
+ */
+export type RegisterInbox = (ctx: HandlerContext) => Unregister;
+
+/** Handle returned to the runtime: teardown + the poller-facing pipeline/tagger. */
+export interface TriagedInboxRegistration {
+  readonly unregister: Unregister;
+  /** Score (+persist) a batch of polled items. Used by the inbox poller. */
+  runInboxTriage(
+    items: readonly InboundChannelItem[],
+    options?: RunInboxTriageOptions,
+  ): Promise<RunInboxTriageResult>;
+  /** Provider-side tagger (IMAP flag / Slack or Discord reaction/tag). */
+  readonly tagger: TriageTagger;
+}
+
+type StoredHandler = GatewayMethodHandler;
+
+interface EnrichmentProxy {
+  readonly ctx: HandlerContext;
+  /** Close the shared triage store handle (if one was ever opened). */
+  dispose(): void;
+}
+
+/**
+ * Build a HandlerContext whose catalog decorates `channels.inbox.list`
+ * registration. The triage store is opened lazily ONCE on the first list
+ * invocation and reused for every subsequent call (hot read path); the caller
+ * disposes the handle on teardown.
+ */
+function withInboxEnrichment(ctx: HandlerContext): EnrichmentProxy {
+  const original = ctx.catalog;
+
+  let store: HandlerSqliteStore | null = null;
+  let initPromise: Promise<HandlerSqliteStore> | null = null;
+  const getStore = async (): Promise<HandlerSqliteStore> => {
+    if (store) return store;
+    if (!initPromise) {
+      const pending = createTriageStore(ctx.workingDirectory);
+      initPromise = pending
+        .init()
+        .then(() => {
+          store = pending;
+          return pending;
+        })
+        .catch((error) => {
+          initPromise = null; // allow a later call to retry opening the store
+          throw error;
+        });
+    }
+    return initPromise;
+  };
+  const dispose = (): void => {
+    if (store) {
+      store.close();
+      store = null;
+    }
+    initPromise = null;
+  };
+
+  const decoratedRegister: GatewayMethodCatalog['register'] = (
+    descriptor: GatewayMethodDescriptor,
+    handler?: StoredHandler,
+    options?: { replace?: boolean },
+  ): Unregister => {
+    if (descriptor.id !== INBOX_LIST_METHOD_ID || !handler) {
+      return original.register(descriptor, handler, options);
+    }
+    const innerHandler = handler;
+    const wrapped: StoredHandler = async (invocation) => {
+      const result = (await innerHandler(invocation)) as InboxListResult;
+      if (!result || !Array.isArray(result.items) || result.items.length === 0) {
+        return result;
+      }
+      const items = result.items as Array<{ id: string }>;
+      try {
+        const handle = await getStore();
+        return { ...result, items: enrichItemsWithTriage(handle, items) };
+      } catch (error) {
+        // Triage is best-effort: a missing/locked store must never break the
+        // read-only inbox feed. Log and return the un-enriched result.
+        ctx.logger.warn('triage: inbox enrichment skipped', {
+          message: summarizeError(error),
+        });
+        return result;
+      }
+    };
+    return original.register(descriptor, wrapped, options);
+  };
+
+  // Clone the context with only `catalog.register` swapped. Every other catalog
+  // method (invoke/list/get/...) keeps pointing at the original instance.
+  const proxiedCatalog = new Proxy(original, {
+    get(target, prop, receiver) {
+      if (prop === 'register') return decoratedRegister;
+      return Reflect.get(target, prop, receiver);
+    },
+  }) as GatewayMethodCatalog;
+
+  return { ctx: { ...ctx, catalog: proxiedCatalog }, dispose };
+}
+
+/**
+ * Compose the triage pipeline with the inbox surface so channels.inbox.list
+ * returns pre-scored items. Returns the teardown plus the poller-facing
+ * pipeline/tagger handle. The inbox surface's registration is wrapped; inbox
+ * teardown runs first, then the shared store handle is disposed.
+ */
+export function registerTriagedInbox(
+  ctx: HandlerContext,
+  registerInbox: RegisterInbox,
+  options: RegisterTriagedInboxOptions = {},
+): TriagedInboxRegistration {
+  const tagger = createTriageTagger(ctx, options.tagger);
+  const enriched = withInboxEnrichment(ctx);
+
+  let unregisterInbox: Unregister;
+  try {
+    unregisterInbox = registerInbox(enriched.ctx);
+  } catch (error) {
+    enriched.dispose();
+    throw error;
+  }
+
+  const unregister: Unregister = () => {
+    try {
+      unregisterInbox();
+    } finally {
+      enriched.dispose();
+    }
+  };
+
+  return {
+    unregister,
+    runInboxTriage: (items, runOptions) =>
+      runInboxTriage(items, ctx, { ...options.pipeline, ...runOptions }),
+    tagger,
+  };
+}
+
+export type { ApplyTagsRequest, ApplyTagsResult };

package/src/daemon/{triage → handlers/triage}/pipeline.ts

@@ -6,25 +6,24 @@
 // later channels.inbox.list response can surface pre-scored items.
 //
 // The inbox surface owns the authoritative cursor-store and exposes
-// triageScore/triageTags columns. To stay strictly within src/daemon/triage/
-// (per the hard rules), this pipeline persists into a dedicated, co-located
-// OperatorSqliteStore ('inbox-triage.sqlite') keyed by item id. The inbox
-// surface reads these rows by id when assembling its list response. The schema
-// mirrors the agreed columns: triageScore REAL, triageTags TEXT (JSON array).
+// triageScore/triageTags columns. To stay strictly within the triage handler
+// surface, this pipeline persists into a dedicated, co-located
+// HandlerSqliteStore ('inbox-triage.sqlite') keyed by item id. The inbox
+// surface reads these rows by id when assembling its list response (the
+// integration decorator does exactly that). The schema mirrors the agreed
+// columns: triageScore REAL, triageTags TEXT (JSON array).
 // ---------------------------------------------------------------------------
 
-import {
-  OperatorSqliteStore,
-  type InboundChannelItem,
-  type OperatorContext,
-} from '../operator/index.ts';
+import { HandlerSqliteStore } from '../sqlite-store.ts';
+import type { HandlerContext } from '../context.ts';
+import type { InboundChannelItem, TriageLabel } from './types.ts';
 import {
   labelToTag,
   scoreInboundItem,
-  type TriageLabel,
   type TriageScore,
   type TriageScorerOptions,
 } from './scorer.ts';
+import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 
 export const TRIAGE_STORE_FILE = 'inbox-triage.sqlite';
 
@@ -57,7 +56,7 @@ export interface TriagedItem extends InboundChannelItem {
 export interface RunInboxTriageOptions {
   scorer?: TriageScorerOptions;
   /** Inject a store (tests). When omitted, a triage store is opened/closed. */
-  store?: OperatorSqliteStore;
+  store?: HandlerSqliteStore;
   /** When true, do not persist — only compute (used by inbox.triage.list). */
   dryRun?: boolean;
   /** Clock injection for deterministic updatedAt in tests. */
@@ -83,8 +82,8 @@ function toMetadata(score: TriageScore): TriageMetadata {
  * Open the triage store for this working directory. Caller owns close()/save()
  * when they pass their own store; otherwise runInboxTriage manages lifecycle.
  */
-export function createTriageStore(workingDirectory: string): OperatorSqliteStore {
-  return new OperatorSqliteStore({
+export function createTriageStore(workingDirectory: string): HandlerSqliteStore {
+  return new HandlerSqliteStore({
     workingDirectory,
     fileName: TRIAGE_STORE_FILE,
     schema: SCHEMA,
@@ -92,7 +91,7 @@ export function createTriageStore(workingDirectory: string): OperatorSqliteStore
 }
 
 function persistRow(
-  store: OperatorSqliteStore,
+  store: HandlerSqliteStore,
   item: InboundChannelItem,
   meta: TriageMetadata,
   updatedAt: string,
@@ -131,7 +130,7 @@ function persistRow(
  */
 export async function runInboxTriage(
   items: readonly InboundChannelItem[],
-  ctx: OperatorContext,
+  ctx: HandlerContext,
   options: RunInboxTriageOptions = {},
 ): Promise<RunInboxTriageResult> {
   const now = options.now ?? (() => new Date());
@@ -160,7 +159,7 @@ export async function runInboxTriage(
     if (ownsStore) await store.save();
   } catch (error) {
     ctx.logger.error('triage: failed to persist scores', {
-      message: error instanceof Error ? error.message : String(error),
+      message: summarizeError(error),
     });
     throw error;
   } finally {
@@ -170,11 +169,7 @@ export async function runInboxTriage(
   return { items: enriched, scored: enriched.length, persisted };
 }
 
-/**
- * Inbound item enriched with the persisted triage metadata that
- * `channels.inbox.list` advertises (triageScore + triageTags). When no triage
- * row exists yet for an item the original item is returned unchanged.
- */
+/** Optional persisted triage metadata overlaid onto an inbound item. */
 export interface TriageOverlay {
   triageScore?: number;
   triageTags?: string[];
@@ -184,46 +179,6 @@ export interface TriageOverlay {
 /** An inbound item overlaid with optional persisted triage metadata. */
 export type TriageEnrichedItem = InboundChannelItem & TriageOverlay;
 
-/**
- * Merge persisted triage metadata onto a batch of inbound items by id. This is
- * the exact glue `channels.inbox.list` invokes to surface pre-scored items: the
- * inbox surface lists from its cursor store, then calls this to overlay the
- * triageScore/triageTags columns the contract promises. Items without a stored
- * triage row pass through untouched, so an un-scored feed degrades gracefully.
- */
-export function enrichItemsWithTriage<T extends { id: string }>(
-  store: OperatorSqliteStore,
-  items: readonly T[],
-): Array<T & TriageOverlay> {
-  if (items.length === 0) return [];
-  // Single batched read (`WHERE id IN (...)`) instead of one SELECT per item —
-  // this is a hot read path (every channels.inbox.list call), so the N+1 is
-  // collapsed to one query keyed by id.
-  const byId = readTriageMetadataBatch(
-    store,
-    items.map((item) => item.id),
-  );
-  return items.map((item) => {
-    const meta = byId.get(item.id);
-    if (!meta) return { ...item };
-    return {
-      ...item,
-      triageScore: meta.triageScore,
-      triageLabel: meta.triageLabel,
-      triageTags: meta.triageTags,
-    };
-  });
-}
-
-interface TriageRow {
-  id: string;
-  triageScore: number;
-  triageLabel: string;
-  triageTags: string;
-  spamSignal: number;
-  prioritySignal: number;
-}
-
 function rowToMetadata(row: Omit<TriageRow, 'id'>): TriageMetadata {
   let tags: string[] = [];
   try {
@@ -240,13 +195,22 @@ function rowToMetadata(row: Omit<TriageRow, 'id'>): TriageMetadata {
   };
 }
 
+interface TriageRow {
+  id: string;
+  triageScore: number;
+  triageLabel: string;
+  triageTags: string;
+  spamSignal: number;
+  prioritySignal: number;
+}
+
 /**
  * Read persisted triage rows for many item ids in a single `WHERE id IN (...)`
  * query. Returns a Map keyed by item id; ids without a stored row are absent.
  * De-duplicates ids so the placeholder list stays minimal.
  */
 export function readTriageMetadataBatch(
-  store: OperatorSqliteStore,
+  store: HandlerSqliteStore,
   itemIds: readonly string[],
 ): Map<string, TriageMetadata> {
   const out = new Map<string, TriageMetadata>();
@@ -266,16 +230,10 @@ export function readTriageMetadataBatch(
 
 /** Read a single persisted triage row by item id (used by the inbox surface). */
 export function readTriageMetadata(
-  store: OperatorSqliteStore,
+  store: HandlerSqliteStore,
   itemId: string,
 ): TriageMetadata | null {
-  const row = store.get<{
-    triageScore: number;
-    triageLabel: string;
-    triageTags: string;
-    spamSignal: number;
-    prioritySignal: number;
-  }>(
+  const row = store.get<Omit<TriageRow, 'id'>>(
     `SELECT triageScore, triageLabel, triageTags, spamSignal, prioritySignal
        FROM inbox_triage WHERE id = ?`,
     [itemId],
@@ -283,3 +241,34 @@ export function readTriageMetadata(
   if (!row) return null;
   return rowToMetadata(row);
 }
+
+/**
+ * Merge persisted triage metadata onto a batch of inbound items by id. This is
+ * the exact glue `channels.inbox.list` invokes to surface pre-scored items: the
+ * inbox surface lists from its cursor store, then calls this to overlay the
+ * triageScore/triageTags columns the contract promises. Items without a stored
+ * triage row pass through untouched, so an un-scored feed degrades gracefully.
+ */
+export function enrichItemsWithTriage<T extends { id: string }>(
+  store: HandlerSqliteStore,
+  items: readonly T[],
+): Array<T & TriageOverlay> {
+  if (items.length === 0) return [];
+  // Single batched read (`WHERE id IN (...)`) instead of one SELECT per item —
+  // this is a hot read path (every channels.inbox.list call), so the N+1 is
+  // collapsed to one query keyed by id.
+  const byId = readTriageMetadataBatch(
+    store,
+    items.map((item) => item.id),
+  );
+  return items.map((item) => {
+    const meta = byId.get(item.id);
+    if (!meta) return { ...item };
+    return {
+      ...item,
+      triageScore: meta.triageScore,
+      triageLabel: meta.triageLabel,
+      triageTags: meta.triageTags,
+    };
+  });
+}