@batalabs/virlow-mcp-core 3.18.0 → 3.68.0

package/dist/notes.js

@@ -1,13 +1,178 @@
-import { bytesToBase64, decryptNoteFields, encryptNoteFields } from '@batalabs/virlow-crypto';
+import { bytesToBase64, decryptNoteFields, decryptTitleField, encryptNoteFields } from '@batalabs/virlow-crypto';
 import { computeExposure } from './exposure.js';
+import { ATTRS_MAX_BYTES, SCHEMA_MAX_BYTES, decodeAttrs, decodeSchema, defineProp, emptyAttrs, emptySchema, encodeAttrs, encodeSchema, newPropId, formatProp, sortedProps, updateProp, homeWidgets, } from './attrs.js';
+import { buildTitleMatcher, extractLinkIds, htmlToText } from './attrs-extract.js';
+import { LockedError } from './vault.js';
 /** Hard ceiling on how many notes searchNotes() will decrypt+scan in a
  * single call. Keeps a single search bounded even for very large accounts;
- * `truncated` tells the caller when the account holds more than this. */
+ * `truncated` tells the caller when the account holds more than this. Also
+ * bounds listVisibleRows(), which backs mention-matching and backlinks(). */
 export const SEARCH_SCAN_CAP = 500;
 const SEARCH_PAGE_LIMIT = 50;
 /** Window radius (chars) either side of the match start when building a
  * content snippet; total window is up to 2*SNIPPET_RADIUS. */
 const SNIPPET_RADIUS = 80;
+/** The one wording every "the vault locked while this was in flight" guard
+ * uses, so the sentence the caller reads cannot drift between them. */
+function lockedError() {
+    return new LockedError('Vault is locked. Ask the user to run the unlock tool to sign in and unlock their Virlow vault.');
+}
+const TRUE_WORDS = new Set(['true', 'yes', 'y', '1', 'on', 'done', 'checked']);
+const FALSE_WORDS = new Set(['false', 'no', 'n', '0', 'off']);
+/** A date value has to start with a calendar day; anything after it (a time,
+ * a zone) is dropped, since a property date is a day. */
+const DATE_PREFIX = /^\d{4}-\d{2}-\d{2}/;
+/** The offending value, echoed back so the caller can see what it sent.
+ * Errors travel to the caller and are never logged, so this is not a
+ * disclosure path for note content. */
+function describeValue(raw) {
+    const text = JSON.stringify(raw);
+    return text === undefined ? String(raw) : text;
+}
+/** The definition a `values` key names, by id or by name (case-insensitive).
+ * Never guesses between two properties sharing a name: a schema written by an
+ * older client can contain duplicates, and picking one silently would write
+ * the value onto whichever happened to sort first. */
+function findDefinition(defs, nameOrId) {
+    const byId = defs.find((d) => d.id === nameOrId);
+    if (byId)
+        return byId;
+    const wanted = nameOrId.trim().toLowerCase();
+    const byName = defs.filter((d) => d.name.trim().toLowerCase() === wanted);
+    if (byName.length > 1) {
+        throw new Error(`"${nameOrId}" names ${byName.length} properties in this folder. Use the id instead: ` +
+            `${byName.map((d) => d.id).join(', ')}.`);
+    }
+    const [only] = byName;
+    if (only)
+        return only;
+    const known = defs.map((d) => d.name).join(', ');
+    throw new Error(`This note's folder has no property "${nameOrId}". Defined properties: ${known || '(none)'}. ` +
+        'Run list_properties to see them, or define_property to add one.');
+}
+/**
+ * Turns the plain JSON a model sends (`{ Stage: "Shipped", Count: 3 }`) into
+ * typed PropValues keyed by property id, plus the options that had to be
+ * invented along the way.
+ *
+ * Nothing is written here: the caller decides the write order, which matters,
+ * because a value naming an option id the definition does not carry is
+ * unreadable in the app and cannot be repaired through this tool.
+ */
+function resolveValues(defs, values, createOption) {
+    const props = {};
+    const applied = [];
+    const newOptions = new Map();
+    /** Every option this call may resolve against: the definition's own, plus
+     * the ones invented for it earlier in this same call, so `["New", "New"]`
+     * resolves to one option rather than two with the same name. */
+    const pool = (def) => [
+        ...(def.options ?? []),
+        ...(newOptions.get(def.id) ?? []),
+    ];
+    const optionId = (def, given) => {
+        const wanted = given.trim();
+        if (wanted === '') {
+            throw new Error(`Property "${def.name}" was given an empty option name.`);
+        }
+        const options = pool(def);
+        const match = options.find((o) => o.id === wanted) ??
+            options.find((o) => o.name.trim().toLowerCase() === wanted.toLowerCase());
+        if (match)
+            return match.id;
+        if (!createOption) {
+            const names = (def.options ?? []).map((o) => o.name).join(', ');
+            throw new Error(`Property "${def.name}" has no option "${wanted}". Valid options: ${names || '(none defined)'}. ` +
+                'Pass createOption: true to add it to the folder\'s property definition.');
+        }
+        const option = { id: newPropId(), name: wanted };
+        newOptions.set(def.id, [...(newOptions.get(def.id) ?? []), option]);
+        return option.id;
+    };
+    const optionName = (def, id) => pool(def).find((o) => o.id === id)?.name ?? id;
+    const asString = (def, raw) => {
+        if (typeof raw === 'string')
+            return raw;
+        if (typeof raw === 'number' || typeof raw === 'boolean')
+            return String(raw);
+        throw new Error(`Property "${def.name}" expects a string, got ${describeValue(raw)}.`);
+    };
+    const asStrings = (def, raw) => Array.isArray(raw) ? raw.map((item) => asString(def, item)) : [asString(def, raw)];
+    const coerce = (def, raw) => {
+        switch (def.type) {
+            case 'text': {
+                const v = asString(def, raw);
+                return { value: { t: 'text', v }, display: v };
+            }
+            case 'url': {
+                const v = asString(def, raw);
+                return { value: { t: 'url', v }, display: v };
+            }
+            case 'number': {
+                const n = typeof raw === 'number'
+                    ? raw
+                    : typeof raw === 'string' && raw.trim() !== ''
+                        ? Number(raw)
+                        : Number.NaN;
+                if (!Number.isFinite(n)) {
+                    throw new Error(`Property "${def.name}" expects a number, got ${describeValue(raw)}.`);
+                }
+                return { value: { t: 'number', v: n }, display: String(n) };
+            }
+            case 'checkbox': {
+                const word = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+                const b = typeof raw === 'boolean'
+                    ? raw
+                    : TRUE_WORDS.has(word)
+                        ? true
+                        : FALSE_WORDS.has(word)
+                            ? false
+                            : null;
+                if (b === null) {
+                    throw new Error(`Property "${def.name}" expects true or false, got ${describeValue(raw)}.`);
+                }
+                return { value: { t: 'checkbox', v: b }, display: b ? 'Yes' : 'No' };
+            }
+            case 'date': {
+                const given = asString(def, raw).trim();
+                if (!DATE_PREFIX.test(given)) {
+                    throw new Error(`Property "${def.name}" expects a date like 2026-09-07, got ${describeValue(raw)}.`);
+                }
+                const v = given.slice(0, 10);
+                return { value: { t: 'date', v }, display: v };
+            }
+            case 'select': {
+                const id = optionId(def, asString(def, raw));
+                return { value: { t: 'select', v: id }, display: optionName(def, id) };
+            }
+            case 'multiSelect': {
+                const ids = asStrings(def, raw).map((name) => optionId(def, name));
+                return {
+                    value: { t: 'multiSelect', v: ids },
+                    display: ids.map((id) => optionName(def, id)).join(', '),
+                };
+            }
+            case 'relation': {
+                const ids = asStrings(def, raw)
+                    .map((id) => id.trim())
+                    .filter((id) => id !== '');
+                return { value: { t: 'relation', v: ids }, display: ids.join(', ') };
+            }
+        }
+    };
+    for (const [nameOrId, raw] of Object.entries(values)) {
+        const def = findDefinition(defs, nameOrId);
+        if (raw === null) {
+            props[def.id] = null;
+            applied.push({ name: def.name, value: 'removed' });
+            continue;
+        }
+        const { value, display } = coerce(def, raw);
+        props[def.id] = value;
+        applied.push({ name: def.name, value: display });
+    }
+    return { props, applied, newOptions };
+}
 export class NotesService {
     api;
     vault;
@@ -15,6 +180,33 @@ export class NotesService {
      * so re-reading/re-scanning the same note twice in one unlock doesn't
      * re-run AES-GCM decryption. Cleared whenever the vault locks. */
     decryptCache = new Map();
+    /** Per-unlock cache of decoded attrs, keyed the same way as decryptCache.
+     * Stores `null` too (a note with no attrs), so `.has()` rather than a
+     * truthiness check distinguishes "decoded, no attrs" from "not cached
+     * yet". Cleared on lock alongside decryptCache. */
+    attrsCache = new Map();
+    /** Per-unlock cache of decrypted titles only (no content), used by
+     * mention-matching and backlinks() so neither has to pay for a full body
+     * decrypt just to learn a note's title. Cleared on lock alongside the
+     * other caches. */
+    titleCache = new Map();
+    /** Per-unlock cache of decoded folder schemas, keyed on the folder id and
+     * the ciphertext itself so a schema this service just rewrote is never
+     * served from a stale entry. Cleared on lock alongside the other caches. */
+    schemaCache = new Map();
+    /**
+     * The rows listVisibleRows() last paged, with the epoch and folder-exposure
+     * they were computed under. Without this, update_note paged the entire note
+     * list on every call just to build mention titles, so one edit cost as many
+     * round trips as the account has pages of notes.
+     *
+     * Keyed on the exposure as well as the epoch, so flipping a folder's
+     * "Expose to MCP" switch takes effect on the very next call rather than
+     * leaving a closed folder's titles in the mention set; dropped outright on
+     * every write, so a note this service just created, moved, trashed or
+     * retitled is never missing from (or stale in) the next scan.
+     */
+    visibleRowsCache = null;
     /** Bumped every time the vault locks (see handleLock()). decryptRow()
      * captures this before its await on decryptNoteFields() and re-checks it
      * afterward, so a decrypt that was still in flight when the vault locked
@@ -33,8 +225,18 @@ export class NotesService {
     }
     handleLock() {
         this.decryptCache.clear();
+        this.attrsCache.clear();
+        this.titleCache.clear();
+        this.schemaCache.clear();
+        this.visibleRowsCache = null;
         this.epoch++;
     }
+    /** Drops the paged row list after anything that could change which rows
+     * exist, where they live, or what they are called. Called after the write
+     * lands, so a failed write leaves the cache alone. */
+    invalidateVisibleRows() {
+        this.visibleRowsCache = null;
+    }
     async listNotes(params) {
         const key = this.requireSession();
         const { notes, pagination } = await this.api.listNotes({ ...params, deleted: false });
@@ -63,6 +265,76 @@ export class NotesService {
         }));
         return { notes: mapped, pagination, withheld, exposure };
     }
+    /**
+     * A folder the way a view shows it: every note in it, with the value it
+     * carries for each of the folder's property definitions.
+     *
+     * The program's AI-parity principle is that every capability the UI gains,
+     * the tools gain in the same epic. The app can now read a folder as a table,
+     * a board or a calendar; without this an assistant could read and write
+     * individual properties but never see the shape the user is looking at, so
+     * "which of these is still in review" meant reading every note in turn.
+     *
+     * Values come from the attrs blob already on each list row, so a folder of
+     * two thousand notes answers without fetching or decrypting a single body.
+     * That is the same constraint the views are built to, and it is why this
+     * reads rows rather than calling readNote per note.
+     *
+     * Hidden notes and unexposed folders are filtered exactly as listNotes does,
+     * and for the same reasons; the counts it withholds are reported here too so
+     * a filtered folder is never mistaken for a small one.
+     */
+    async listFolderView(params) {
+        const key = this.requireSession();
+        const folder = await this.requireFolder(params.folderId);
+        const defs = sortedProps(await this.decodeSchemaFor(key, folder));
+        const { notes, pagination } = await this.api.listNotes({
+            folderId: params.folderId,
+            page: params.page,
+            limit: params.limit,
+            deleted: false,
+        });
+        const exposure = await this.exposure();
+        const notHidden = notes.filter((row) => row.hidden !== true);
+        const visible = notHidden.filter((row) => exposure.allows(row.folderId));
+        const withheld = {
+            inClosedFolders: notHidden.length - visible.length,
+        };
+        const rows = await Promise.all(visible.map(async (row) => {
+            const attrs = await this.decodeAttrsFor(key, row);
+            const values = {};
+            for (const def of defs) {
+                values[def.id] = formatProp(def, attrs?.props?.[def.id]);
+            }
+            return {
+                id: row.id,
+                title: await this.decryptTitleFor(key, row),
+                values,
+            };
+        }));
+        // Sorting on the formatted value, as the table does, so a select orders by
+        // its option name rather than by an option id nobody chose. An empty value
+        // sorts last, so asking for an order never buries the rows that have data.
+        const sortedBy = params.sortBy
+            ? (defs.find((d) => d.id === params.sortBy) ??
+                defs.find((d) => d.name.toLowerCase() === params.sortBy.toLowerCase()) ??
+                null)
+            : null;
+        if (sortedBy) {
+            rows.sort((a, b) => {
+                const ka = a.values[sortedBy.id] ?? '';
+                const kb = b.values[sortedBy.id] ?? '';
+                if (ka === kb)
+                    return 0;
+                if (ka === '')
+                    return 1;
+                if (kb === '')
+                    return -1;
+                return ka.localeCompare(kb);
+            });
+        }
+        return { defs, rows, pagination, withheld, sortedBy };
+    }
     async readNote(id) {
         const key = this.requireSession();
         const row = await this.api.getNote(id);
@@ -71,12 +343,19 @@ export class NotesService {
         const exposure = await this.exposure();
         this.requireExposed(exposure, row.folderId, id);
         const { title, content } = await this.decryptRow(key, row);
-        return { id: row.id, title, content, folderId: row.folderId };
+        const attrs = await this.decodeAttrsFor(key, row);
+        return { id: row.id, title, content, folderId: row.folderId, attrs };
     }
     async createNote(title, content, folderId, type) {
         const key = this.requireSession();
+        // Same guard as updateNote(): captured before the encrypt await so a
+        // lock landing mid-create is caught before the write, not after.
+        const startEpoch = this.epoch;
         const salt = bytesToBase64(crypto.getRandomValues(new Uint8Array(32)));
         const { encryptedTitle, encryptedContent, iv } = await encryptNoteFields(key, title, content);
+        if (this.epoch !== startEpoch) {
+            throw lockedError();
+        }
         const body = {
             title: '[ENCRYPTED]',
             content: '[ENCRYPTED]',
@@ -90,27 +369,278 @@ export class NotesService {
         if (type !== undefined)
             body.type = type;
         const row = await this.api.createNote(body);
+        this.invalidateVisibleRows();
         return { id: row.id };
     }
     updateNote(id, changes) {
         return this.enqueue(async () => {
             const key = this.requireSession();
+            // Captured before any await so a lock that lands mid-update is caught
+            // before the write, not after: this note's ciphertext must never be
+            // sent encrypted under a key the vault has since revoked.
+            const startEpoch = this.epoch;
             const existingRow = await this.api.getNote(id);
             const exposure = await this.exposure();
             this.requireExposed(exposure, existingRow.folderId, id);
             const current = await this.decryptRow(key, existingRow);
             const title = changes.title ?? current.title;
             const content = changes.content ?? current.content;
-            const salt = bytesToBase64(crypto.getRandomValues(new Uint8Array(32)));
-            const { encryptedTitle, encryptedContent, iv } = await encryptNoteFields(key, title, content);
-            await this.api.updateNote(id, {
-                title: '[ENCRYPTED]',
-                content: '[ENCRYPTED]',
-                encryptedTitle,
-                encryptedContent,
-                iv,
-                salt,
+            const prevAttrs = (await this.decodeAttrsFor(key, existingRow)) ?? emptyAttrs();
+            const props = { ...prevAttrs.props };
+            for (const [propKey, value] of Object.entries(changes.props ?? {})) {
+                if (value === null) {
+                    delete props[propKey];
+                }
+                else {
+                    props[propKey] = value;
+                }
+            }
+            const links = extractLinkIds(content).filter((linkId) => linkId !== id);
+            // Reuses the exposure already computed above for requireExposed(),
+            // rather than making visibleTitles() fetch the folder list again.
+            const titles = await this.visibleTitles(key, id, exposure);
+            const mentions = buildTitleMatcher(titles).find(htmlToText(content), new Set([id, ...links]));
+            const attrs = {
+                // `v` comes from prevAttrs (1 via emptyAttrs() when there was no
+                // previous blob); it is never overwritten with a literal 1 here, so
+                // a blob written by a newer client that bumped `v` keeps its number
+                // through this round trip instead of being silently downgraded.
+                ...prevAttrs,
+                props,
+                links,
+                mentions,
+                updated: new Date().toISOString(),
+                ...(changes.aliases !== undefined ? { aliases: changes.aliases } : {}),
+            };
+            const encryptedAttrs = await this.encodeAttrsChecked(key, attrs, id);
+            // A props-or-aliases-only edit leaves the body exactly as it was, so it
+            // sends only the attrs blob. Re-encrypting the unchanged title and
+            // content would rewrite the row's ciphertext (and its IV and salt) for
+            // no reason: pure work, a bigger request, a pointless revision, and one
+            // more chance for an unrelated failure to corrupt a body nobody asked
+            // to change.
+            const body = { encryptedAttrs };
+            if (changes.title !== undefined || changes.content !== undefined) {
+                const salt = bytesToBase64(crypto.getRandomValues(new Uint8Array(32)));
+                const { encryptedTitle, encryptedContent, iv } = await encryptNoteFields(key, title, content);
+                body.title = '[ENCRYPTED]';
+                body.content = '[ENCRYPTED]';
+                body.encryptedTitle = encryptedTitle;
+                body.encryptedContent = encryptedContent;
+                body.iv = iv;
+                body.salt = salt;
+            }
+            if (this.epoch !== startEpoch) {
+                throw lockedError();
+            }
+            await this.api.updateNote(id, body);
+            this.invalidateVisibleRows();
+        });
+    }
+    /**
+     * Notes that link to `id`, built entirely from attrs, never a body
+     * decrypt. Scans the same folder-visible, non-hidden rows as listNotes(),
+     * bounded by SEARCH_SCAN_CAP like searchNotes().
+     *
+     * Unlike readNote()/decryptRow(), which let an in-flight decrypt finish and
+     * simply skip the cache write if the vault locked mid-flight, this
+     * aggregates across every visible note in one call: a lock partway through
+     * means the result mixes attrs decoded under a session that's since been
+     * revoked, which is not safe to hand back. So the whole call rejects with
+     * LockedError instead.
+     */
+    async backlinks(id) {
+        const key = this.requireSession();
+        const startEpoch = this.epoch;
+        const rows = await this.listVisibleRows();
+        const result = [];
+        for (const row of rows) {
+            if (row.id === id)
+                continue;
+            const attrs = await this.decodeAttrsFor(key, row);
+            if (attrs?.links.includes(id)) {
+                result.push({ id: row.id, title: await this.decryptTitleFor(key, row) });
+            }
+        }
+        if (this.epoch !== startEpoch) {
+            throw lockedError();
+        }
+        return result;
+    }
+    /** A folder's property definitions, in display order. Read-only, so no
+     * mutation queue and no epoch guard past the read itself. */
+    async listProperties(folderId) {
+        const key = this.requireSession();
+        const folder = await this.requireFolder(folderId);
+        return sortedProps(await this.decodeSchemaFor(key, folder));
+    }
+    /** A folder's dashboard as it stands, with the blocks it will draw. */
+    async readDashboard(folderId) {
+        const key = this.requireSession();
+        const folder = await this.requireFolder(folderId);
+        const schema = await this.decodeSchemaFor(key, folder);
+        return {
+            widgets: homeWidgets(schema, sortedProps(schema)),
+            defs: sortedProps(schema),
+            arranged: (schema.home?.widgets?.length ?? 0) > 0,
+        };
+    }
+    /**
+     * Replaces a folder's dashboard arrangement.
+     *
+     * The previous arrangement is kept alongside the new one, so a person can
+     * put back what an assistant changed. That matters more here than for a
+     * note: a note edit is visible in the note, while a dashboard edit can
+     * remove a block and leave nothing behind to say what was there. One level,
+     * deliberately: this is an undo, not a history, and the schema travels
+     * inside every folder read.
+     */
+    setDashboard(folderId, widgets) {
+        return this.enqueue(async () => {
+            const key = this.requireSession();
+            // Captured before the first await, re-checked immediately before the
+            // write, exactly as updateNote() does.
+            const startEpoch = this.epoch;
+            const folder = await this.requireFolder(folderId);
+            const schema = await this.decodeSchemaFor(key, folder);
+            const kept = homeWidgets(schema, sortedProps(schema));
+            // The date on a summary is stamped here rather than taken from the
+            // caller. It records when the text was actually written, which is a
+            // fact about this write and not a claim for an assistant to make; one
+            // that forgot to send it would otherwise leave a snapshot with nothing
+            // to say how old it is, which is the whole reason the field exists.
+            const now = new Date().toISOString();
+            const stamped = widgets.map((w) => w.kind === 'summary' ? { ...w, at: now } : w);
+            const next = {
+                ...schema,
+                home: { ...schema.home, widgets: stamped, previous: kept },
+            };
+            const encryptedSchema = await this.encodeSchemaChecked(key, next, folderId);
+            if (this.epoch !== startEpoch)
+                throw lockedError();
+            await this.api.updateFolder(folderId, { encryptedSchema });
+            return stamped;
+        });
+    }
+    /**
+     * Appends a property definition to a folder's schema.
+     *
+     * Refuses a name the folder already uses, rather than creating a second
+     * definition with it: setProperties() resolves a value's key by name, and a
+     * duplicate would make every later call ambiguous. The message names the
+     * existing id so the caller can just use it.
+     */
+    defineProperty(folderId, def) {
+        return this.enqueue(async () => {
+            const key = this.requireSession();
+            // Captured before the first await, re-checked immediately before the
+            // write, exactly as updateNote() does.
+            const startEpoch = this.epoch;
+            const folder = await this.requireFolder(folderId);
+            const schema = await this.decodeSchemaFor(key, folder);
+            const name = def.name.trim();
+            const clash = sortedProps(schema).find((p) => p.name.trim().toLowerCase() === name.toLowerCase());
+            if (clash) {
+                throw new Error(`Folder ${folderId} already has a property named "${clash.name}" (id ${clash.id}, ` +
+                    `type ${clash.type}). Use that id, or choose a different name.`);
+            }
+            const id = newPropId();
+            const options = (def.options ?? []).map((o) => ({ id: newPropId(), name: o.name.trim() }));
+            const next = defineProp(schema, {
+                id,
+                name,
+                type: def.type,
+                ...(options.length > 0 ? { options } : {}),
+                ...(def.showInList !== undefined ? { showInList: def.showInList } : {}),
             });
+            // Narrowing, not a guess: defineProp() appends exactly what it was
+            // given, so this finds it. Looked up rather than reconstructed so the
+            // definition reported back is the one actually written.
+            const created = sortedProps(next).find((p) => p.id === id);
+            if (created === undefined) {
+                throw new Error(`Could not define property "${name}" in folder ${folderId}.`);
+            }
+            const encryptedSchema = await this.encodeSchemaChecked(key, next, folderId);
+            if (this.epoch !== startEpoch)
+                throw lockedError();
+            await this.api.updateFolder(folderId, { encryptedSchema });
+            return created;
+        });
+    }
+    /**
+     * Sets typed property values on one note, keyed by property name or id.
+     *
+     * Only `encryptedAttrs` is sent: the title and body keep the ciphertext,
+     * IV and salt they already had, so a property change can never damage a
+     * body nobody asked to change.
+     *
+     * When `createOption` invents an option for a select or multiSelect, the
+     * definition carrying it is written to the folder **before** the value that
+     * names it. Get that order wrong and a failure in between leaves a value
+     * pointing at an option id no definition carries, which reads as blank in
+     * the app and cannot be repaired from here. In this order the worst a
+     * failure between the two writes leaves behind is an option nobody uses
+     * yet, and repeating the same call finds that option by name, adds no
+     * duplicate, and writes the value.
+     */
+    setProperties(noteId, values, opts = {}) {
+        // Shares updateNote()'s queue: a property write and a body write on the
+        // same note must not interleave their read-merge-encrypt-write cycles.
+        return this.enqueue(async () => {
+            const key = this.requireSession();
+            const startEpoch = this.epoch;
+            if (Object.keys(values).length === 0) {
+                throw new Error(`No values given for note ${noteId}. Run list_properties on its folder to see what ` +
+                    'can be set, and pass at least one value.');
+            }
+            const row = await this.api.getNote(noteId);
+            const { folders } = await this.api.listFolders();
+            const exposure = this.exposureOf(folders);
+            this.requireExposed(exposure, row.folderId, noteId);
+            const folder = folders.find((f) => f.id === row.folderId);
+            if (folder === undefined) {
+                // Narrowing: requireExposed() above only passes for a folder that is
+                // in this same list, so there is always one to find.
+                throw new Error(`Note ${noteId}'s folder was not found.`);
+            }
+            const schema = await this.decodeSchemaFor(key, folder);
+            const defs = sortedProps(schema);
+            const { props: patch, applied, newOptions } = resolveValues(defs, values, opts.createOption === true);
+            // The attrs blob is built and size-checked before anything is written,
+            // so a note whose properties would not fit never costs the folder an
+            // orphan option.
+            const prevAttrs = (await this.decodeAttrsFor(key, row)) ?? emptyAttrs();
+            const props = { ...prevAttrs.props };
+            for (const [propId, value] of Object.entries(patch)) {
+                if (value === null) {
+                    delete props[propId];
+                }
+                else {
+                    props[propId] = value;
+                }
+            }
+            // `v` and every unknown field come from prevAttrs, so a blob written by
+            // a newer client survives this round trip (see updateNote()).
+            const attrs = { ...prevAttrs, props, updated: new Date().toISOString() };
+            const encryptedAttrs = await this.encodeAttrsChecked(key, attrs, noteId);
+            if (newOptions.size > 0) {
+                let nextSchema = schema;
+                for (const [defId, added] of newOptions) {
+                    const def = defs.find((d) => d.id === defId);
+                    nextSchema = updateProp(nextSchema, defId, {
+                        options: [...(def?.options ?? []), ...added],
+                    });
+                }
+                const encryptedSchema = await this.encodeSchemaChecked(key, nextSchema, folder.id);
+                if (this.epoch !== startEpoch)
+                    throw lockedError();
+                await this.api.updateFolder(folder.id, { encryptedSchema });
+            }
+            if (this.epoch !== startEpoch)
+                throw lockedError();
+            await this.api.updateNote(noteId, { encryptedAttrs });
+            this.invalidateVisibleRows();
+            return { attrs, applied };
         });
     }
     async searchNotes(query, limit = 20) {
@@ -168,6 +698,7 @@ export class NotesService {
             this.requireExposed(exposure, folderId, id);
         }
         await this.api.updateNote(id, { folderId });
+        this.invalidateVisibleRows();
     }
     async setStar(id, starred) {
         this.requireSession();
@@ -175,6 +706,7 @@ export class NotesService {
         const exposure = await this.exposure();
         this.requireExposed(exposure, existingRow.folderId, id);
         await this.api.updateNote(id, { starred });
+        this.invalidateVisibleRows();
     }
     async archiveNote(id, archived) {
         this.requireSession();
@@ -182,6 +714,7 @@ export class NotesService {
         const exposure = await this.exposure();
         this.requireExposed(exposure, existingRow.folderId, id);
         await this.api.updateNote(id, { archived });
+        this.invalidateVisibleRows();
     }
     async trashNote(id) {
         this.requireSession();
@@ -189,6 +722,7 @@ export class NotesService {
         const exposure = await this.exposure();
         this.requireExposed(exposure, existingRow.folderId, id);
         await this.api.updateNote(id, { deleted: true });
+        this.invalidateVisibleRows();
     }
     async listFolders() {
         this.requireSession();
@@ -207,7 +741,22 @@ export class NotesService {
      * respect it. */
     async exposure() {
         const { folders } = await this.api.listFolders();
-        return computeExposure(folders);
+        return this.exposureOf(folders);
+    }
+    /** The same computation for a caller that already has the folder list and
+     * needs a folder out of it as well as the exposure (the property tools do:
+     * a folder's schema and its exposure come from the same row). */
+    exposureOf(folders) {
+        // Everything computeExposure() actually reads, in list order. Any change
+        // to it changes which notes are visible, so it invalidates the paged row
+        // cache keyed on this string. The key travels on the exposure object
+        // rather than in an instance field: two calls can be in flight at once,
+        // and a field would let the second one's key be stamped onto rows the
+        // first one filtered under a different exposure.
+        const key = folders
+            .map((f) => `${f.id}/${f.parentId ?? ''}/${f.mcpEnabled ? 1 : 0}/${f.kind ?? ''}`)
+            .join('|');
+        return { ...computeExposure(folders), key };
     }
     /** Throws unless `folderId` is exposed to MCP. Every method that reads or
      * mutates a specific note (by id) must call this — knowing a note's id is
@@ -243,6 +792,166 @@ export class NotesService {
         }
         return fields;
     }
+    /** Decode (with per-unlock caching) a note's attrs blob. Mirrors
+     * decryptRow()'s epoch guard: a decode still in flight when the vault
+     * locks resolves for its own caller but never lands in the cache. */
+    async decodeAttrsFor(key, row) {
+        // Keyed on the encrypted blob itself, not just id:updatedAt like
+        // decryptCache: title/content changes always bump updatedAt together with
+        // their ciphertext, but an attrs-only write (or a caller handing in a row
+        // it patched in memory) can leave updatedAt behind while encryptedAttrs
+        // changed, and a stale hit here would silently serve the wrong props.
+        const cacheKey = `${row.id}:${row.updatedAt}:${row.encryptedAttrs ?? ''}`;
+        if (this.attrsCache.has(cacheKey)) {
+            return this.attrsCache.get(cacheKey) ?? null;
+        }
+        const startEpoch = this.epoch;
+        const attrs = await decodeAttrs(key, row.encryptedAttrs);
+        if (this.epoch === startEpoch) {
+            this.attrsCache.set(cacheKey, attrs);
+        }
+        return attrs;
+    }
+    /** Decrypt (with per-unlock caching) just a note's title, without touching
+     * its body, the cheaper primitive backlinks() and mention-matching need. */
+    async decryptTitleFor(key, row) {
+        if (!row.encryptedTitle) {
+            return row.title;
+        }
+        const cacheKey = `${row.id}:${row.updatedAt}`;
+        const cached = this.titleCache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const startEpoch = this.epoch;
+        const title = await decryptTitleField(key, row.encryptedTitle, row.iv ?? '');
+        if (this.epoch === startEpoch) {
+            this.titleCache.set(cacheKey, title);
+        }
+        return title;
+    }
+    /** The folder-visible, non-hidden rows a mention/backlink scan is allowed to
+     * see, same exposure rules as listNotes()/searchNotes(), bounded by
+     * SEARCH_SCAN_CAP for the same reason searchNotes() is. Accepts an
+     * already-computed `exposure` so a caller that has just checked it (as
+     * updateNote() has, for requireExposed()) does not pay for a second
+     * listFolders() round trip. */
+    async listVisibleRows(exposure) {
+        const exp = exposure ?? (await this.exposure());
+        const startEpoch = this.epoch;
+        const key = `${startEpoch}:${exp.key}`;
+        if (this.visibleRowsCache?.key === key)
+            return this.visibleRowsCache.rows;
+        const rows = [];
+        let page = 1;
+        for (;;) {
+            const { notes, pagination } = await this.api.listNotes({ page, limit: SEARCH_PAGE_LIMIT, deleted: false });
+            for (const row of notes) {
+                if (row.hidden === true)
+                    continue;
+                // Archived notes are out of the way by the user's own choice, so an
+                // archived note is not a backlink source and not a mention target.
+                // The web index excludes them for the same reason; without this,
+                // get_backlinks and the web disagreed about the same vault.
+                if (row.archived === true)
+                    continue;
+                if (!exp.allows(row.folderId))
+                    continue;
+                rows.push(row);
+                if (rows.length >= SEARCH_SCAN_CAP) {
+                    this.cacheVisibleRows(key, startEpoch, rows);
+                    return rows;
+                }
+            }
+            if (notes.length === 0 || page >= pagination.pages)
+                break;
+            page++;
+        }
+        this.cacheVisibleRows(key, startEpoch, rows);
+        return rows;
+    }
+    /** Same guard as decryptRow(): a paging run that was still in flight when
+     * the vault locked must not seed the cache for the session that follows. */
+    cacheVisibleRows(key, startEpoch, rows) {
+        if (this.epoch !== startEpoch)
+            return;
+        this.visibleRowsCache = { key, rows };
+    }
+    /** Title entries for mention-matching against a note being saved: one entry
+     * per other folder-visible note's title, plus one more per alias in its
+     * attrs (an alias is another name mentions should recognize, same as the
+     * title). Titles come from decryptTitleFor() and aliases from
+     * decodeAttrsFor() (the same per-epoch caches backlinks() uses), so this
+     * costs no body decryption. */
+    async visibleTitles(key, excludeId, exposure) {
+        const rows = await this.listVisibleRows(exposure);
+        const entries = [];
+        for (const row of rows) {
+            if (row.id === excludeId)
+                continue;
+            entries.push({ id: row.id, title: await this.decryptTitleFor(key, row) });
+            const attrs = await this.decodeAttrsFor(key, row);
+            for (const alias of attrs?.aliases ?? []) {
+                entries.push({ id: row.id, title: alias });
+            }
+        }
+        return entries;
+    }
+    /** The folder a property tool was pointed at, refused unless it exists and
+     * the user has opened it to MCP. Knowing a folder id is no more consent
+     * than knowing a note id is (see requireExposed). */
+    async requireFolder(folderId) {
+        const { folders } = await this.api.listFolders();
+        const folder = folders.find((f) => f.id === folderId);
+        if (folder === undefined) {
+            throw new Error(`There is no folder ${folderId}. Run list_folders to see the folders exposed to MCP.`);
+        }
+        if (!this.exposureOf(folders).allows(folder.id)) {
+            throw new Error(`Folder ${folderId} is not exposed to MCP. Turn on "Expose to MCP" in that folder's ` +
+                'settings in the Virlow app to access it here.');
+        }
+        return folder;
+    }
+    /** Decode (with per-unlock caching) a folder's property definitions. A
+     * folder that has never had any decodes to an empty schema rather than
+     * null, so every caller can treat the two the same way. */
+    async decodeSchemaFor(key, folder) {
+        if (!folder.encryptedSchema)
+            return emptySchema();
+        const cacheKey = `${folder.id}:${folder.encryptedSchema}`;
+        const cached = this.schemaCache.get(cacheKey);
+        if (cached)
+            return cached;
+        const startEpoch = this.epoch;
+        const schema = (await decodeSchema(key, folder.encryptedSchema)) ?? emptySchema();
+        // Same guard as decryptRow(): a decode still in flight when the vault
+        // locks resolves for its own caller but never seeds the next session.
+        if (this.epoch === startEpoch) {
+            this.schemaCache.set(cacheKey, schema);
+        }
+        return schema;
+    }
+    /** Encrypts a folder schema and enforces the server's size cap
+     * client-side, the way encodeAttrsChecked() does for a note's attrs. */
+    async encodeSchemaChecked(key, schema, folderId) {
+        const encryptedSchema = await encodeSchema(key, schema);
+        const byteLength = new TextEncoder().encode(encryptedSchema).length;
+        if (byteLength > SCHEMA_MAX_BYTES) {
+            throw new Error(`Folder ${folderId}'s property definitions are too large to save (${byteLength} bytes, ` +
+                `limit ${SCHEMA_MAX_BYTES}). Remove some properties or options and try again.`);
+        }
+        return encryptedSchema;
+    }
+    /** Encrypts attrs and enforces the server's size cap client-side: an
+     * oversized blob is refused with a clear message rather than sent and
+     * bounced back as an HTTP 413 `ATTRS_TOO_LARGE`. */
+    async encodeAttrsChecked(key, attrs, id) {
+        const encryptedAttrs = await encodeAttrs(key, attrs);
+        const byteLength = new TextEncoder().encode(encryptedAttrs).length;
+        if (byteLength > ATTRS_MAX_BYTES) {
+            throw new Error(`Note ${id}'s properties and aliases are too large to save (${byteLength} bytes, limit ${ATTRS_MAX_BYTES}). Remove some properties, tags, or aliases and try again.`);
+        }
+        return encryptedAttrs;
+    }
     buildSnippet(title, content, contentMatchIndex) {
         if (contentMatchIndex === -1) {
             return title;