@coffer-org/server 2.5.2 → 2.6.1

package/dist/collection-io.js

@@ -2,6 +2,7 @@ import { serialize } from '@mikro-orm/core';
 import { collectionGroups, fieldEntries, storageColumns } from '@coffer-org/sdk/shelf';
 import { isGroup, isEmbeddedGroup, isJsonStored } from '@coffer-org/sdk/fields';
 import { chunk } from "./batch.js";
+import { selectRows } from "./read-rows.js";
 function flattenLayout(fields) {
     const out = [];
     for (const f of fields) {
@@ -68,7 +69,7 @@ export async function readAt(em, prefix, fields, parentId) {
     for (const c of collectionGroups(fields)) {
         const table = `${prefix}__${c.key}`;
         const childFields = c.group.fields;
-        const rows = serialize(await em.find(table, { parent_id: parentId }, { orderBy: { position: 'asc' } }));
+        const rows = (await selectRows(em, table, { parent_id: parentId }, { orderBy: { position: 'asc' } }));
         const acc = [];
         for (const row of rows) {
             const { id, parent_id: _pid, position: _pos, ...rest } = row;
@@ -90,9 +91,7 @@ export async function readAtMany(em, prefix, fields, parentIds) {
         const childFields = c.group.fields;
         const rows = [];
         for (const ids of chunk(parentIds)) {
-            rows.push(...serialize(await em.find(table, { parent_id: { $in: ids } }, {
-                orderBy: { position: 'asc' },
-            })));
+            rows.push(...(await selectRows(em, table, { parent_id: { $in: ids } }, { orderBy: { position: 'asc' } })));
         }
         const nestedByChild = await readAtMany(em, table, childFields, rows.map((r) => r.id));
         for (const id of parentIds)

package/dist/embeddings.d.ts

@@ -25,6 +25,7 @@ export declare function cosine(a: ArrayLike<number>, b: ArrayLike<number>): numb
 export declare function twoPassSearch(rows: EmbeddingRow[], queryVec: ArrayLike<number>, k: number, opts?: {
     coarseDims?: number;
     poolMinFactor?: number;
+    shelfKeys?: Set<string>;
 }): EmbeddingHit[];
 export declare function upsertEmbedding(args: {
     shelfKey: string;
@@ -34,5 +35,7 @@ export declare function upsertEmbedding(args: {
     model: string;
 }): Promise<void>;
 export declare function deleteEmbedding(shelfKey: string, recordId: number): Promise<void>;
-export declare function searchEmbeddings(queryVec: number[], k: number): Promise<EmbeddingHit[]>;
+export declare function searchEmbeddings(queryVec: number[], k: number, opts?: {
+    shelfKeys?: Set<string>;
+}): Promise<EmbeddingHit[]>;
 export declare function listEventsSince(lastId: number, limit: number): Promise<EventRow[]>;

package/dist/embeddings.js

@@ -59,7 +59,8 @@ export function cosine(a, b) {
     return denom ? dot / denom : 0;
 }
 export function twoPassSearch(rows, queryVec, k, opts = {}) {
-    const N = rows.length;
+    const scope = opts.shelfKeys ? rows.filter((r) => opts.shelfKeys.has(r.shelfKey)) : rows;
+    const N = scope.length;
     if (N === 0)
         return [];
     const coarseDims = opts.coarseDims ?? COARSE_DIMS;
@@ -68,13 +69,13 @@ export function twoPassSearch(rows, queryVec, k, opts = {}) {
     const m = Math.min(coarseDims, qFull.length);
     const qSmall = qFull.subarray(0, m);
     const poolSize = Math.min(N, Math.max(k * poolMinFactor, Math.ceil(N * 0.1)));
-    const pool = rows
+    const pool = scope
         .map((r, i) => ({ i, d: 1 - cosine(r.full.subarray(0, m), qSmall) }))
         .sort((a, b) => a.d - b.d)
         .slice(0, poolSize);
     return pool
         .map(({ i }) => {
-        const r = rows[i];
+        const r = scope[i];
         return { shelfKey: r.shelfKey, recordId: r.recordId, snippet: r.snippet, distance: 1 - cosine(r.full, qFull) };
     })
         .sort((a, b) => a.distance - b.distance)
@@ -99,8 +100,8 @@ export async function deleteEmbedding(shelfKey, recordId) {
     await em.nativeDelete('_Embedding', { shelf_key: shelfKey, record_id: recordId });
     invalidateEmbeddingCache();
 }
-export async function searchEmbeddings(queryVec, k) {
-    return twoPassSearch(await loadCache(), queryVec, k);
+export async function searchEmbeddings(queryVec, k, opts = {}) {
+    return twoPassSearch(await loadCache(), queryVec, k, opts);
 }
 export async function listEventsSince(lastId, limit) {
     const em = getEm().fork();

package/dist/extend-table.js

@@ -1,17 +1,16 @@
-import { serialize } from '@mikro-orm/core';
 import { getEm } from "./db.js";
 import { splitAt, writeAt, readAt, readAtMany, deleteAt } from "./collection-io.js";
 import { chunk } from "./batch.js";
+import { selectRows } from "./read-rows.js";
 export function extendEntityName(e) {
     return `extend__${e.id}`;
 }
 export async function getExtendRecord(e, baseId, em) {
     const fork = em ?? getEm().fork();
     const name = extendEntityName(e);
-    const row = await fork.findOne(name, { base_id: baseId });
-    if (!row)
+    const [flat] = (await selectRows(fork, name, { base_id: baseId }, { limit: 1 }));
+    if (!flat)
         return undefined;
-    const flat = serialize(row);
     const collections = await readAt(fork, name, e.fields, baseId);
     return { ...flat, ...collections };
 }
@@ -23,7 +22,7 @@ export async function getExtendRecords(e, baseIds, em) {
     const name = extendEntityName(e);
     const flats = [];
     for (const ids of chunk(baseIds)) {
-        flats.push(...serialize(await fork.find(name, { base_id: { $in: ids } })));
+        flats.push(...(await selectRows(fork, name, { base_id: { $in: ids } })));
     }
     if (flats.length === 0)
         return out;

package/dist/global-search.js

@@ -1,10 +1,10 @@
 import { textSearchKeys, titleKey, recordTitle, storageColumnsFor } from '@coffer-org/sdk/shelf';
-import { serialize } from '@mikro-orm/core';
 import { tokenize } from '@coffer-org/core/search';
 import { getLogger } from '@coffer-org/sdk/logger';
 import { getEm } from "./db.js";
 import { rowMatch } from "./records-api.js";
 import { ftsAvailable, ftsCandidates, MIN_FTS_QUERY_LENGTH } from "./search-index.js";
+import { selectRows } from "./read-rows.js";
 const log = getLogger('search');
 export const SEARCH_SCAN_LIMIT = 1000;
 function matchCols(m) {
@@ -44,10 +44,7 @@ export async function globalSearchByScan(shelves, q, limit) {
             continue;
         if (!textSearchKeys(shelf.def).length)
             continue;
-        const rows = (await fork.find(shelf.table, {}, {
-            limit: SEARCH_SCAN_LIMIT,
-            fields: matchCols(shelf.def),
-        })).map((r) => serialize(r));
+        const rows = await selectRows(fork, shelf.table, {}, { limit: SEARCH_SCAN_LIMIT, fields: matchCols(shelf.def) });
         if (rows.length === SEARCH_SCAN_LIMIT) {
             log.warn('scan cap reached', { shelf: shelf.key, limit: SEARCH_SCAN_LIMIT });
         }
@@ -77,9 +74,7 @@ export async function globalSearch(shelves, q, limit) {
             continue;
         if (!textSearchKeys(shelf.def).length)
             continue;
-        const rows = (await fork.find(shelf.table, { id: { $in: ids } }, {
-            fields: matchCols(shelf.def),
-        })).map((r) => serialize(r));
+        const rows = await selectRows(fork, shelf.table, { id: { $in: ids } }, { fields: matchCols(shelf.def) });
         scored.push(...scoreRows(shelf, rows, tokens));
     }
     scored.sort((a, b) => b.score - a.score || tieKey(a.result).localeCompare(tieKey(b.result)));

package/dist/index.js

@@ -24,7 +24,7 @@ import { baseUrl } from "./public-url.js";
 import { discoverPluginAssets, discoverRuntime } from "./plugin-discovery.js";
 import { checkLatestVersion, resolveUpdateTarget, resolveAllUpdateTargets, resolveBaseTargets, resolveRuntimeTarget, runNpmInstall, } from "./plugin-updates.js";
 import { buildClientSchema } from "./schema-api.js";
-import { recordList, recordListPage, isPagedRequest, recordGet, recordCreate, recordUpdate, recordDelete, recordRestore, recordPurge, recordTrashList, MAX_PAGE, UnknownShelfError, } from "./records-api.js";
+import { recordList, recordListPage, isPagedRequest, recordGet, recordCreate, recordUpdate, recordDelete, recordRestore, recordPurge, recordTrashList, MAX_PAGE, UnknownShelfError, ensureSingle, SingleShelfError, } from "./records-api.js";
 import { maskTree, preserveTree } from "./field-masking.js";
 import { writePluginSettings } from "./settings-write.js";
 import { rootLogger, getLogger } from "./log.js";
@@ -125,6 +125,8 @@ async function guard(reply, fn) {
     catch (e) {
         if (e instanceof ValidationError)
             return reply.code(422).send({ error: 'validation', issues: e.issues });
+        if (e instanceof SingleShelfError)
+            return reply.code(409).send({ error: 'single_shelf', message: e.message });
         if (e instanceof NotFoundError)
             return reply.code(404).send({ error: 'not_found' });
         app.log.error(e);
@@ -365,6 +367,11 @@ function maskRecordRow(library, shelf, row) {
     }
     return out;
 }
+function listRow(library, shelf, row) {
+    const out = maskRecordRow(library, shelf, row);
+    const activity = out._activity;
+    return activity ? { ...out, _activity: { favorite: activity.favorite === true } } : out;
+}
 app.get('/api/trash', async (_req, reply) => {
     const rows = await recordTrashList();
     return rows.map((entry) => ({ ...entry, record: maskRecordRow(entry.library, entry.shelf, entry.record) }));
@@ -415,7 +422,7 @@ app.get('/api/:library/:shelf', async (req, reply) => {
             let rows = await recordList(library, shelf, query, opts);
             if (req.user && tracksRecordActivity(req.headers))
                 rows = await applySmartRanking(req.user.id, library, shelf, rows);
-            return rows.map((r) => maskRecordRow(library, shelf, r));
+            return rows.map((r) => listRow(library, shelf, r));
         }
         const pageOpts = {
             ...opts,
@@ -431,7 +438,7 @@ app.get('/api/:library/:shelf', async (req, reply) => {
             const pageOffset = Math.max(0, Number.isFinite(pageOpts.offset) ? Math.trunc(pageOpts.offset) : 0);
             page = { rows: ranked.slice(pageOffset, pageOffset + pageLimit), total: ranked.length };
         }
-        return { rows: page.rows.map((r) => maskRecordRow(library, shelf, r)), total: page.total };
+        return { rows: page.rows.map((r) => listRow(library, shelf, r)), total: page.total };
     }
     catch (e) {
         if (e instanceof UnknownShelfError)
@@ -476,6 +483,15 @@ app.patch('/api/:library/:shelf/:id/activity', async (req, reply) => {
         throw e;
     }
 });
+app.get('/api/:library/:shelf/single', async (req, reply) => {
+    const { library, shelf } = req.params;
+    const m = getShelf(library, shelf);
+    if (!m)
+        return reply.code(404).send({ error: 'unknown_shelf' });
+    if (!m.single)
+        return reply.code(404).send({ error: 'not_single_shelf' });
+    return maskRecordRow(library, shelf, await ensureSingle(library, shelf));
+});
 app.get('/api/:library/:shelf/:id', async (req, reply) => {
     const { library, shelf, id } = req.params;
     const rid = Number(id);

package/dist/mcp-local.js

@@ -1,5 +1,5 @@
 import { ValidationError, NotFoundError } from '@coffer-org/mcp/client';
-import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, recordTrashList, recordRestore, recordPurge, } from "./records-api.js";
+import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, recordTrashList, recordRestore, recordPurge, SingleShelfError, } from "./records-api.js";
 import { ValidationError as ServerValidationError } from "./mutate.js";
 import { buildClientSchema } from "./schema-api.js";
 export function mapError(e) {
@@ -7,6 +7,8 @@ export function mapError(e) {
         throw new ValidationError(e.issues ?? []);
     if (e instanceof UnknownShelfError)
         throw new NotFoundError('not_found');
+    if (e instanceof SingleShelfError)
+        throw new ValidationError([{ field: 'shelf', code: 'single_shelf', message: e.message }]);
     throw e;
 }
 export function splitListQuery(raw) {

package/dist/mcp-tools.d.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { type ToolResult } from '@coffer-org/mcp';
 import { type AuthRole, type PluginHooks } from './plugin-hooks.ts';
 import { type Condition } from '@coffer-org/sdk/condition';
-import { type EmbeddingHit } from './embeddings.ts';
+import { type RagHit } from './rag-search.ts';
 export interface McpToolDef {
     server: string;
     bareName: string;
@@ -17,7 +17,7 @@ export interface McpToolDef {
 export interface RagDeps {
     embeddingApiKey: string;
 }
-export declare function formatHits(hits: EmbeddingHit[]): string;
+export declare function formatHits(hits: RagHit[]): string;
 export declare function resolveRagDeps(): Promise<RagDeps | null>;
 export declare function collectMcpTools(opts?: {
     rag?: RagDeps | null;
@@ -28,6 +28,19 @@ export declare function collectPluginInstructions(hooks?: Record<string, PluginH
     id: string;
     instructions: string;
 }[]>;
+type SingleShelf = {
+    library: string;
+    shelf: string;
+    claude: string;
+};
+export declare function collectSingleShelves(reg?: {
+    shelves: {
+        library: string;
+        shelf: string;
+        single?: boolean;
+        claude?: string;
+    }[];
+}): SingleShelf[];
 type LibraryPurpose = {
     id: string;
     agent: string;

package/dist/mcp-tools.js

@@ -10,7 +10,8 @@ import { countTargetsFor, recordCounts } from "./counts.js";
 import { describeCondition } from '@coffer-org/sdk/condition';
 import { getEm } from "./db.js";
 import { getPluginSettings } from "./plugin-runtime.js";
-import { searchEmbeddings } from "./embeddings.js";
+import { configuredPublicUrl } from "./public-url.js";
+import { hybridSearch, buildSearchShelves } from "./rag-search.js";
 import { embedOne, embeddingFailureMessage } from "./embed-openai.js";
 import { getLogger } from "./log.js";
 import { writePluginSettings, listSettings } from "./settings-write.js";
@@ -21,7 +22,14 @@ export function formatHits(hits) {
     if (hits.length === 0)
         return 'No matching records.';
     return hits
-        .map((h) => `[${h.shelfKey}/${h.recordId}] (dist ${h.distance.toFixed(3)})\n${h.snippet}`)
+        .map((h) => {
+        const legs = [];
+        if (h.distance != null)
+            legs.push(`vector ${h.distance.toFixed(3)} #${h.vectorRank}`);
+        if (h.textRank != null)
+            legs.push(`text #${h.textRank}`);
+        return `[${h.shelfKey}/${h.recordId}] (${legs.join(' | ')})\n${h.snippet}`;
+    })
         .join('\n\n');
 }
 const ok = (data) => ({
@@ -64,11 +72,16 @@ export async function collectMcpTools(opts = {}) {
             role: 'member',
             handler: async () => {
                 const { token, expiresInSec } = mintUploadTicket(actor);
+                const base = await configuredPublicUrl();
+                const uploadUrl = base ? `${base}/api/upload` : '/api/upload';
                 return ok({
                     token,
-                    upload_url: '/api/upload',
+                    upload_url: uploadUrl,
                     expires_in: expiresInSec,
-                    how_to: 'curl -H "Authorization: Bearer <token>" -F "file=@<path>" <base-url>/api/upload  →  {"name":"<name>"}. Then set a file field to {"name":"<name>"}. mime/size are filled in by the server — do not send your own.',
+                    how_to: `curl -H "Authorization: Bearer <token>" -F "file=@<path>" ${uploadUrl}  →  {"name":"<name>"}. Then set a file field to {"name":"<name>"}. mime/size are filled in by the server — do not send your own.` +
+                        (base
+                            ? ''
+                            : ' The server has no public URL configured (core settings publicUrl / PUBLIC_URL env), so the path is relative — resolve it against this MCP server\'s own origin.'),
                 });
             },
         });
@@ -132,18 +145,55 @@ export async function collectMcpTools(opts = {}) {
             server: 'rag',
             bareName: 'search_records',
             httpName: 'search_records',
-            description: "Semantic search over the user's coffer records. Returns the most relevant records as library/shelf/id refs with a text snippet.",
-            inputSchema: { query: z.string(), k: z.number().int().positive().optional() },
+            description: "Hybrid search over the user's coffer records: semantic similarity plus exact-token matching. " +
+                'Returns the most relevant records as library/shelf/id refs with a text snippet. Narrow it with `library` ' +
+                '(and optionally `shelf`) when you already know where the answer lives. An empty result means nothing ' +
+                'relevant is stored — say so instead of answering from a weak match. If the first call returns nothing ' +
+                'useful, retry with a rephrasing, or with the exact literal string (a model number, a name, an error code): ' +
+                'the exact-token leg finds those where a paraphrase cannot.',
+            inputSchema: {
+                query: z.string(),
+                k: z.number().int().positive().optional(),
+                library: z.string().optional(),
+                shelf: z.string().optional(),
+            },
             scope: 'rag',
             role: 'member',
             handler: async (args) => {
+                const library = args.library;
+                const shelf = args.shelf;
+                if (shelf && !library) {
+                    return fail('Error: `shelf` needs `library` (a shelf name is only unique inside its library).');
+                }
+                if (library) {
+                    const known = buildSearchShelves({ library, shelf });
+                    if (known.length === 0) {
+                        const all = buildSearchShelves();
+                        const valid = shelf
+                            ? all.filter((s) => s.key.startsWith(`${library}/`)).map((s) => s.key)
+                            : [...new Set(all.map((s) => s.key.split('/')[0]))];
+                        return fail(`Error: unknown ${shelf ? 'shelf' : 'library'}. Valid: ${valid.join(', ')}`);
+                    }
+                }
+                let vector = null;
+                try {
+                    vector = (await embedOne(args.query, embeddingApiKey)).vector;
+                }
+                catch (e) {
+                    log.warn(`embedding failed, text-only search — ${embeddingFailureMessage(e)}`);
+                }
                 try {
-                    const { vector } = await embedOne(args.query, embeddingApiKey);
-                    const hits = await searchEmbeddings(vector, args.k ?? DEFAULT_RAG_TOP_K);
+                    const hits = await hybridSearch({
+                        query: args.query,
+                        vector,
+                        k: args.k ?? DEFAULT_RAG_TOP_K,
+                        library,
+                        shelf,
+                    });
                     return { content: [{ type: 'text', text: formatHits(hits) }] };
                 }
                 catch (e) {
-                    return fail(`RAG unavailable: ${embeddingFailureMessage(e)} Use the regular coffer tools (list_records/get_record) instead.`);
+                    return fail(`Search unavailable: ${e.message} Use the regular coffer tools (list_records/get_record) instead.`);
                 }
             },
         });
@@ -214,6 +264,22 @@ export async function collectPluginInstructions(hooks = pluginHooks, emFactory =
     }
     return out;
 }
+export function collectSingleShelves(reg) {
+    let registry = reg;
+    if (!registry) {
+        try {
+            registry = getActiveRegistry();
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!registry)
+        return [];
+    return registry.shelves
+        .filter((s) => s.single && s.claude)
+        .map((s) => ({ library: s.library, shelf: s.shelf, claude: s.claude }));
+}
 export function collectLibraryPurposes(reg) {
     let registry = reg;
     if (!registry) {
@@ -259,6 +325,13 @@ export async function buildDomainSections() {
         overview =
             '## Libraries (what each holds / when to use it — pick the right one before searching)\n\n' + blocks.join('\n\n');
     }
+    const singles = collectSingleShelves();
+    const singleSection = singles.length
+        ? '## Single-record shelves (one document each — read the record, do not search the shelf)\n\n' +
+            singles
+                .map((s) => `- ${s.library}/${s.shelf}: ${s.claude.replace(/\s*\n\s*/g, ' ')}`)
+                .join('\n')
+        : null;
     const dataModel = '## Data model\n' +
         'Library (top-level area) → shelf (a kind of record, e.g. things/item) → record (addressed library/shelf/id) → fields. ' +
         'Some field values are JSON (e.g. quantity {"value":2000,"unit":"ml"}); some are relations (hold another record\'s id); ' +
@@ -273,6 +346,7 @@ export async function buildDomainSections() {
     return [
         dataModel,
         ...(overview ? [overview] : []),
+        ...(singleSection ? [singleSection] : []),
         ...(site ? [`## web\n${site}`] : []),
         ...rules,
     ];
@@ -280,7 +354,7 @@ export async function buildDomainSections() {
 export function buildMcpInstructions(sections) {
     const base = [
         "Coffer is the user's personal database, organized into libraries (kitchen, people, finance, health, devices, home, garden, documents, travel, and more), each holding typed records.",
-        'Use the tools to read and write this data: call list_libraries to see what exists, describe_shelf before create_record/update_record, then list_records / get_record to read. When a search_records tool is available, use it for semantic lookup.',
+        'Use the tools to read and write this data: call list_libraries to see what exists, describe_shelf before create_record/update_record, then list_records / get_record to read. When a search_records tool is available, use it for lookup — it searches by meaning and by exact token at once, and takes an optional library/shelf to narrow it. State where each fact came from by citing its record as [library/shelf/id]: an answer assembled from search results without citations cannot be checked against the data.',
         'The per-library notes below name the shelves and the rules — not every field. For exact field names, types, and which are required, call describe_shelf(library, shelf) rather than guessing from the notes.',
         'Record field values may be JSON-encoded (e.g. quantity {"value":2000,"unit":"ml"}) — parse them.',
         'Action safety: read a complete record before editing or deleting it. update_record must be the smallest patch and must preserve unmentioned fields. delete_record moves the record to reversible trash; never blank fields to simulate deletion. For suspected duplicates, read both complete records, compare fields/collections/extends/attachments, identify the less complete record, and offer a field-by-field merge before moving anything to trash. Use list_trash/restore_record for recovery; purge_record is irreversible and requires explicit confirmation.',

package/dist/mutate.js

@@ -3,6 +3,7 @@ import { buildZodObject, buildZodObjectPartial, fieldEntries } from '@coffer-org
 import { isJsonStored, decodeVmsg } from '@coffer-org/sdk/fields';
 import { resolveFlag } from '@coffer-org/sdk/condition';
 import { getEm } from "./db.js";
+import { selectRows } from "./read-rows.js";
 import { normalizeFileFields, dropUnchangedFileFields, touchesFileFields } from "./file-fields.js";
 import { notifyRecordsChanged } from "./index-signal.js";
 import { encodeTemporal, decodeTemporal } from "./temporal.js";
@@ -54,18 +55,14 @@ export async function listRecords(entityName, opts = {}) {
     const fork = getEm().fork();
     const deleted = opts.deleted ?? 'active';
     const where = deleted === 'active' ? { deleted_at: null } : deleted === 'deleted' ? { deleted_at: { $ne: null } } : {};
-    const rows = await fork.findAll(entityName, { where, orderBy: { id: 'asc' } });
-    return serialize(rows);
+    return selectRows(fork, entityName, where, { orderBy: { id: 'asc' } });
 }
 export async function getRecord(m, entityName, id, opts = {}) {
     const fork = getEm().fork();
-    const row = await fork.findOne(entityName, {
-        id,
-        ...(opts.includeDeleted ? {} : { deleted_at: null }),
-    });
+    const [row] = await selectRows(fork, entityName, { id, ...(opts.includeDeleted ? {} : { deleted_at: null }) }, { limit: 1 });
     if (!row)
         return undefined;
-    const flat = decodeTemporal(m, serialize(row));
+    const flat = decodeTemporal(m, row);
     const nested = nestEmbedded(m, flat);
     const collections = await readCollections(fork, m, id);
     return { ...nested, ...collections };

package/dist/plugin-runtime.js

@@ -1,4 +1,3 @@
-import { serialize } from '@mikro-orm/core';
 import { composeRegistry } from '@coffer-org/core/compose';
 import { getLogger } from '@coffer-org/sdk/logger';
 import { initDb, getOrm, getEm } from "./db.js";
@@ -6,6 +5,7 @@ import { syncSchema } from "./schema-sync.js";
 import { systemEntities, buildPluginEntities, shelfTableName } from "./entity-schema.js";
 import { pluginHooks, pluginCtx, HttpError } from "./plugin-hooks.js";
 import { discoverPlugins, loadServerHooks } from "./plugin-discovery.js";
+import { selectRows } from "./read-rows.js";
 import { runMigrations, assertSafeRequired, renameSystemShelfKey } from "./migrations.js";
 import { runSeeds } from "./seeds.js";
 import { setActiveRegistry } from "./registry-context.js";
@@ -36,12 +36,10 @@ export function getDisabled() {
 export async function getPluginSettings(pluginId) {
     try {
         const fork = getEm().fork();
-        const row = await fork.findOne(`_settings__${pluginId}`, {
-            plugin_id: pluginId,
-        });
+        const [row] = await selectRows(fork, `_settings__${pluginId}`, { plugin_id: pluginId }, { limit: 1 });
         if (!row)
             return {};
-        return serialize(row);
+        return row;
     }
     catch {
         return {};

package/dist/rag-search.d.ts

@@ -0,0 +1,40 @@
+import { type EmbeddingHit } from './embeddings.ts';
+import { type GlobalSearchHit, type SearchShelf } from './global-search.ts';
+export declare const RRF_K = 60;
+export declare const MAX_VECTOR_DISTANCE = 0.85;
+export declare const SEARCH_POOL = 50;
+export interface FusedEntry {
+    score: number;
+    ranks: (number | null)[];
+}
+export declare function fuseRrf<T>(lists: T[][], keyOf: (item: T) => string, k?: number): Map<string, FusedEntry>;
+export interface RagHit {
+    shelfKey: string;
+    recordId: number;
+    snippet: string;
+    distance: number | null;
+    vectorRank: number | null;
+    textRank: number | null;
+    score: number;
+}
+export interface HybridOpts {
+    query: string;
+    vector: number[] | null;
+    k: number;
+    library?: string;
+    shelf?: string;
+    maxDistance?: number;
+    rrfK?: number;
+}
+export interface HybridDeps {
+    vectorSearch?: (vec: number[], k: number, o?: {
+        shelfKeys?: Set<string>;
+    }) => Promise<EmbeddingHit[]>;
+    textSearch?: (shelves: SearchShelf[], q: string, k: number) => Promise<GlobalSearchHit[]>;
+    shelves?: SearchShelf[];
+}
+export declare function buildSearchShelves(filter?: {
+    library?: string;
+    shelf?: string;
+}): SearchShelf[];
+export declare function hybridSearch(opts: HybridOpts, deps?: HybridDeps): Promise<RagHit[]>;

package/dist/rag-search.js

@@ -0,0 +1,95 @@
+import { searchEmbeddings } from "./embeddings.js";
+import { globalSearch } from "./global-search.js";
+import { getActiveRegistry } from "./registry-context.js";
+import { shelfTableName } from "./entity-schema.js";
+import { getLogger } from "./log.js";
+const log = getLogger('rag-search');
+export const RRF_K = 60;
+export const MAX_VECTOR_DISTANCE = 0.85;
+export const SEARCH_POOL = 50;
+export function fuseRrf(lists, keyOf, k = RRF_K) {
+    const out = new Map();
+    lists.forEach((list, listIndex) => {
+        list.forEach((item, i) => {
+            const key = keyOf(item);
+            let entry = out.get(key);
+            if (!entry) {
+                entry = { score: 0, ranks: lists.map(() => null) };
+                out.set(key, entry);
+            }
+            if (entry.ranks[listIndex] !== null)
+                return;
+            entry.ranks[listIndex] = i + 1;
+            entry.score += 1 / (k + i + 1);
+        });
+    });
+    return out;
+}
+export function buildSearchShelves(filter = {}) {
+    return getActiveRegistry()
+        .shelves.filter((m) => (filter.library ? m.library === filter.library : true))
+        .filter((m) => (filter.shelf ? m.shelf === filter.shelf : true))
+        .map((m) => ({
+        key: `${m.library}/${m.shelf}`,
+        table: shelfTableName(m.library, m.shelf),
+        def: m,
+    }));
+}
+const hitKey = (shelfKey, recordId) => `${shelfKey}/${recordId}`;
+async function leg(name, run) {
+    try {
+        return await run();
+    }
+    catch (e) {
+        log.warn(`${name} leg failed, degrading — ${e.message}`);
+        return [];
+    }
+}
+export async function hybridSearch(opts, deps = {}) {
+    const vectorSearch = deps.vectorSearch ?? searchEmbeddings;
+    const textSearch = deps.textSearch ?? globalSearch;
+    const narrowed = Boolean(opts.library || opts.shelf);
+    const shelves = deps.shelves
+        ? deps.shelves
+            .filter((s) => (opts.library ? s.key.startsWith(`${opts.library}/`) : true))
+            .filter((s) => (opts.shelf ? s.key.endsWith(`/${opts.shelf}`) : true))
+        : buildSearchShelves({ library: opts.library, shelf: opts.shelf });
+    const shelfKeys = narrowed ? new Set(shelves.map((s) => s.key)) : undefined;
+    const maxDistance = opts.maxDistance ?? MAX_VECTOR_DISTANCE;
+    const [vectorHits, textHits] = await Promise.all([
+        opts.vector
+            ? leg('vector', () => vectorSearch(opts.vector, SEARCH_POOL, { shelfKeys }))
+            : Promise.resolve([]),
+        leg('text', () => textSearch(shelves, opts.query, SEARCH_POOL)),
+    ]);
+    const near = vectorHits.filter((h) => h.distance <= maxDistance);
+    const keyedText = textHits.map((h) => ({
+        shelfKey: `${h.library}/${h.shelf}`,
+        recordId: Number(h.id),
+        snippet: h.snippet,
+    }));
+    const fused = fuseRrf([near, keyedText], (h) => hitKey(h.shelfKey, h.recordId), opts.rrfK);
+    const snippets = new Map();
+    for (const h of keyedText)
+        snippets.set(hitKey(h.shelfKey, h.recordId), h.snippet);
+    for (const h of near)
+        snippets.set(hitKey(h.shelfKey, h.recordId), h.snippet);
+    const distances = new Map(near.map((h) => [hitKey(h.shelfKey, h.recordId), h.distance]));
+    return [...fused.entries()]
+        .map(([key, entry]) => {
+        const slash = key.lastIndexOf('/');
+        const shelfKey = key.slice(0, slash);
+        return {
+            shelfKey,
+            recordId: Number(key.slice(slash + 1)),
+            snippet: snippets.get(key) ?? '',
+            distance: distances.get(key) ?? null,
+            vectorRank: entry.ranks[0] ?? null,
+            textRank: entry.ranks[1] ?? null,
+            score: entry.score,
+        };
+    })
+        .sort((a, b) => b.score - a.score ||
+        hitKey(a.shelfKey, a.recordId).localeCompare(hitKey(b.shelfKey, b.recordId)))
+        .slice(0, opts.k);
+}

package/dist/read-rows.d.ts

@@ -0,0 +1,8 @@
+import type { EntityManager } from '@mikro-orm/core';
+export type SelectOpts = {
+    fields?: string[];
+    orderBy?: Record<string, 'ASC' | 'DESC' | 'asc' | 'desc'>;
+    limit?: number;
+    offset?: number;
+};
+export declare function selectRows(em: EntityManager, entityName: string, where?: Record<string, unknown>, opts?: SelectOpts): Promise<Record<string, unknown>[]>;

package/dist/read-rows.js

@@ -0,0 +1,11 @@
+export async function selectRows(em, entityName, where = {}, opts = {}) {
+    const qb = em.createQueryBuilder(entityName);
+    qb.select(opts.fields ?? '*').where(where);
+    if (opts.orderBy)
+        qb.orderBy(opts.orderBy);
+    if (opts.limit !== undefined)
+        qb.limit(opts.limit, opts.offset);
+    else if (opts.offset !== undefined)
+        qb.offset(opts.offset);
+    return (await qb.execute('all', true));
+}

package/dist/records-api.d.ts

@@ -1,6 +1,9 @@
 import type { ShelfDef } from '@coffer-org/sdk/shelf';
 export declare class UnknownShelfError extends Error {
 }
+export declare class SingleShelfError extends Error {
+    constructor(message: string);
+}
 export type RecordListQuery = {
     q?: string;
     id?: string;
@@ -33,6 +36,7 @@ export declare function recordGet(library: string, shelf: string, id: number, op
     includeDeleted?: boolean;
 }): Promise<Record<string, unknown> | null>;
 export declare function recordCreate(library: string, shelf: string, body: unknown, actor?: string): Promise<Record<string, unknown>>;
+export declare function ensureSingle(library: string, shelf: string): Promise<Record<string, unknown>>;
 export declare function recordUpdate(library: string, shelf: string, id: number, body: unknown, actor?: string): Promise<Record<string, unknown>>;
 export declare function recordDelete(library: string, shelf: string, id: number, actor?: string): Promise<void>;
 export declare function recordRestore(library: string, shelf: string, id: number, actor?: string): Promise<void>;

package/dist/records-api.js

@@ -1,7 +1,7 @@
 import { fieldMap, textSearchKeys, titleKey, recordTitle, listKeys, storageColumnsFor } from '@coffer-org/sdk/shelf';
 import { tokenize, matchScoreFolded, foldText } from '@coffer-org/core/search';
-import { serialize } from '@mikro-orm/core';
 import { getActiveRegistry, getShelf, getExtendsFor } from "./registry-context.js";
+import { selectRows } from "./read-rows.js";
 import { shelfTableName } from "./entity-schema.js";
 import { getExtendRecord, getExtendRecords } from "./extend-table.js";
 import { getEm } from "./db.js";
@@ -11,11 +11,17 @@ import { createRecord, updateRecord, getRecord, deleteRecord, restoreRecord, pur
 import { deleteRecordActivity } from "./record-activity.js";
 export class UnknownShelfError extends Error {
 }
+export class SingleShelfError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SingleShelfError';
+    }
+}
 export const MAX_PAGE = 500;
 function pickCols(row, cols) {
     const out = {};
     for (const c of cols)
-        if (c in row)
+        if (c in row && row[c] !== null)
             out[c] = row[c];
     return out;
 }
@@ -112,7 +118,7 @@ export async function recordCount(library, shelf, query = {}, opts = {}) {
         return 0;
     return getEm().fork().count(ename, where);
 }
-export async function recordList(library, shelf, query = {}, opts = {}) {
+async function listRecords(library, shelf, query = {}, opts = {}) {
     const { view = 'full', extends: withExt = true, deleted = 'active' } = opts;
     const { m, ename } = resolve(library, shelf);
     const { q, ...filterParams } = query;
@@ -137,7 +143,7 @@ export async function recordList(library, shelf, query = {}, opts = {}) {
         ...(opts.orderBy ? { orderBy: opts.orderBy } : {}),
         ...(sqlSlice ? { limit: opts.limit, offset: Math.max(0, opts.offset ?? 0) } : {}),
     };
-    let rows = (await fork.find(ename, where, (Object.keys(findOpts).length ? findOpts : undefined))).map((r) => serialize(r));
+    let rows = await selectRows(fork, ename, where, findOpts);
     if (tokens.length > 0)
         rows = rows.filter((row) => rowMatch(m, row, tokens) !== null);
     if (projected)
@@ -147,6 +153,12 @@ export async function recordList(library, shelf, query = {}, opts = {}) {
         return decoded;
     return withExtendsMany(decoded, library, shelf);
 }
+export async function recordList(library, shelf, query = {}, opts = {}) {
+    const { m } = resolve(library, shelf);
+    if (m.single)
+        await ensureSingle(library, shelf);
+    return listRecords(library, shelf, query, opts);
+}
 export function isPagedRequest(limit, offset) {
     return [limit, offset].some((v) => v !== undefined && v.trim() !== '' && Number.isFinite(Number(v)));
 }
@@ -179,7 +191,7 @@ export async function recordGet(library, shelf, id, opts = {}) {
         return null;
     return withExtends(row, library, shelf);
 }
-export async function recordCreate(library, shelf, body, actor = 'gui') {
+async function createOne(library, shelf, body, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
     const { base, extData } = splitBody(body);
     validateExtends(library, shelf, extData);
@@ -189,6 +201,37 @@ export async function recordCreate(library, shelf, body, actor = 'gui') {
     });
     return withExtends(row, library, shelf);
 }
+export async function recordCreate(library, shelf, body, actor = 'gui') {
+    const { m } = resolve(library, shelf);
+    if (m.single) {
+        await ensureSingle(library, shelf);
+        throw new SingleShelfError(`single_shelf ${library}/${shelf}: the record already exists — update it instead`);
+    }
+    return createOne(library, shelf, body, actor);
+}
+const singleInFlight = new Map();
+export async function ensureSingle(library, shelf) {
+    const { m } = resolve(library, shelf);
+    if (!m.single)
+        throw new Error(`not a single shelf: ${library}/${shelf}`);
+    const key = `${library}/${shelf}`;
+    const pending = singleInFlight.get(key);
+    if (pending)
+        return pending;
+    const task = (async () => {
+        const rows = await listRecords(library, shelf, {}, { limit: 1, orderBy: { id: 'ASC' } });
+        if (rows[0])
+            return rows[0];
+        return createOne(library, shelf, {}, 'system');
+    })();
+    singleInFlight.set(key, task);
+    try {
+        return await task;
+    }
+    finally {
+        singleInFlight.delete(key);
+    }
+}
 export async function recordUpdate(library, shelf, id, body, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
     const { base, extData } = splitBody(body);
@@ -201,6 +244,8 @@ export async function recordUpdate(library, shelf, id, body, actor = 'gui') {
 }
 export async function recordDelete(library, shelf, id, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
+    if (m.single)
+        throw new SingleShelfError(`single_shelf ${library}/${shelf}: the record cannot be deleted — clear its fields instead`);
     await deleteRecord(m, ename, id, { actor });
 }
 export async function recordRestore(library, shelf, id, actor = 'gui') {
@@ -209,6 +254,8 @@ export async function recordRestore(library, shelf, id, actor = 'gui') {
 }
 export async function recordPurge(library, shelf, id, actor = 'gui') {
     const { m, ename } = resolve(library, shelf);
+    if (m.single)
+        throw new SingleShelfError(`single_shelf ${library}/${shelf}: the record cannot be deleted — clear its fields instead`);
     await purgeRecord(m, ename, id, { actor }, (tx, recordId) => deleteExtends(tx, library, shelf, recordId));
     await deleteRecordActivity(library, shelf, id);
 }
@@ -216,7 +263,7 @@ export async function recordTrashList() {
     const shelves = getActiveRegistry().shelves.filter((s) => s.standalone !== false);
     const out = [];
     for (const m of shelves) {
-        const rows = await recordList(m.library, m.shelf, {}, { view: 'full', extends: true, deleted: 'deleted' });
+        const rows = await listRecords(m.library, m.shelf, {}, { view: 'full', extends: true, deleted: 'deleted' });
         for (const record of rows)
             out.push({ library: m.library, shelf: m.shelf, label: m.label, record });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/server",
-  "version": "2.5.2",
+  "version": "2.6.1",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@coffer-org/core": "^2.1.4",
-    "@coffer-org/sdk": "^2.1.3",
+    "@coffer-org/sdk": "^2.2.0",
     "@extractus/oembed-extractor": "^4.1.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/multipart": "^10.0.0",