@3sln/trove 0.0.2

package/packages/core/src/indexing.js

@@ -0,0 +1,340 @@
+// IndexingCoordinator — the indexing subsystem, extracted from the Vfs façade. Owns
+// the indexer registry, the search index, and the per-file contribution flow:
+//   • indexNode(node)          — run every matching indexer on upload/write
+//   • indexContributions(...)  — apply one contributor's {semanticTexts, tags, metadata}
+//   • removeContributions(...) — clear one contributor from a node
+//   • backfillIndexer(...)     — re-run an indexer over the whole drive (on install)
+//   • purgeIndexer(...)        — remove an indexer's contributions everywhere (uninstall)
+//
+// Vfs holds one of these and delegates; it needs only `storageFor` (collection → blob
+// backend) injected so this stays free of the tree/path concerns.
+
+import { TroveError } from './errors.js';
+import { readAll } from './util.js';
+import { normalizeContribution, clampContribution, DEFAULT_CAPS } from './indexers/contribution.js';
+
+export class IndexingCoordinator {
+  /**
+   * @param {object} deps
+   * @param {import('./metadata/interface.js').MetadataStore} deps.metadata
+   * @param {object|null} deps.search  SearchService (or null when search is disabled)
+   * @param {import('./indexers/registry.js').IndexerRegistry} deps.indexers
+   * @param {(collectionId: string) => Promise<object>} deps.storageFor
+   * @param {number} deps.maxIndexBytes
+   * @param {object} [deps.caps]  contribution size caps (see indexers/contribution.js)
+   * @param {import('./issues.js').IssueRegistry} [deps.issues] where a failure to index
+   *   becomes a standing, retryable problem instead of a console line nobody reads
+   */
+  constructor({ metadata, search, indexers, storageFor, maxIndexBytes, caps, issues, mintUrl = null }) {
+    this.metadata = metadata;
+    this.search = search ?? null;
+    this.indexers = indexers;
+    this.storageFor = storageFor;
+    this.maxIndexBytes = maxIndexBytes;
+    this.caps = { ...DEFAULT_CAPS, ...caps };
+    this.issues = issues ?? null;
+    // How a time-limited read URL is made. Not this file's business any more — it is one
+    // caller of a general primitive (see signedUrls.js), not the owner of a private one.
+    this.mintUrl = mintUrl;
+  }
+
+  /**
+   * Apply one contributor's indexed contribution to a node. A contribution has up
+   * to three scopes: `semanticTexts` (→ search index), `tags` (filterable), and
+   * `metadata` (arbitrary, e.g. a chapter index). Each contributor is namespaced,
+   * so its contribution replaces only its own and can be removed independently.
+   * The legacy `{ documents, facet }` shape is accepted (documents→semanticTexts,
+   * facet→metadata).
+   */
+  async indexContributions(nodeId, contributorId, contribution) {
+    const node = await this.metadata.getById(nodeId);
+    if (!node) throw TroveError.notFound('Node');
+    await this.#applyContribution(nodeId, contributorId, contribution);
+    return { ok: true };
+  }
+
+  /**
+   * THE choke point: every contribution reaches storage through here, whether it came
+   * from a built-in indexer, a plugin indexer in the isolate, or a sandboxed plugin
+   * pushing over the API. So this is where the size caps have to be applied — clamping
+   * inside any one producer would leave the other two unbounded, and the API push is
+   * the one most exposed to untrusted code.
+   */
+  async #applyContribution(nodeId, contributorId, contribution) {
+    const { semanticTexts, tags, metadata } = normalizeContribution(clampContribution(contribution, this.caps));
+    // ALWAYS write the search half, including when it is empty. `indexDocuments` clears
+    // this (node, contributor)'s prior docs before it writes, so passing [] is how you
+    // say "this contributor has nothing to say about this node any more". Skipping the
+    // call when the list is empty meant overwriting a document with blank content left
+    // its old chunks in the index for good — search kept returning the file, with a
+    // snippet of text that was no longer in it.
+    if (this.search) await this.search.indexDocuments(nodeId, contributorId, semanticTexts);
+    // Indexer contributions live in the queryable metadata store (not the sidecar),
+    // so they show up in list/stat and drive tag filtering. Tags MERGE within a
+    // contributor's namespace by design (see applyContribution) — but a contribution
+    // with no scopes at all is that contributor withdrawing, so its facets go too,
+    // rather than leaving an excerpt describing content that no longer exists.
+    if (tags || metadata) await this.metadata.setContribution(nodeId, contributorId, { tags, metadata });
+    else if (!semanticTexts.length) await this.metadata.clearContribution?.(nodeId, contributorId);
+  }
+
+  /** Clear this contributor's search entries for a node (an empty re-index). */
+  async #clearSearch(nodeId, contributorId) {
+    if (this.search) await this.search.indexDocuments(nodeId, contributorId, []).catch(() => {});
+  }
+
+  /** Remove everything a contributor added to a node (search + tags + metadata). */
+  async removeContributions(nodeId, contributorId) {
+    // Re-indexing with no docs clears this (node, contributor)'s vectors + keywords.
+    await this.#clearSearch(nodeId, contributorId);
+    await this.metadata.clearContribution(nodeId, contributorId);
+  }
+
+  /**
+   * Index a freshly written/uploaded node: its name (for keyword search) + every
+   * matching indexer's contribution.
+   *
+   * Whether this succeeded is recorded, not just logged. An item that fails to index is
+   * an item that cannot be found, and in a drive with no folders that is indistinguishable
+   * from an item that isn't there — so the failure becomes a standing issue the user can
+   * see and retry, and the next success clears it.
+   */
+  async indexNode(node) {
+    let failure = null;
+    try {
+      if (this.search) await this.search.indexName(node);
+      const matching = this.indexers.matching(node);
+      if (matching.length) {
+        const storage = await this.storageFor(node.collectionId);
+        const ctx = this.#indexCtx(node, storage);
+        // #runOneIndexer already contains a single indexer's failure; what escapes here
+        // is the shared work (reading the object, the search store itself).
+        for (const indexer of matching) {
+          const err = await this.#runOneIndexer(indexer, node, ctx);
+          if (err && !failure) failure = err;
+        }
+      }
+    } catch (err) {
+      failure = err;
+    }
+    await this.#recordIndexOutcome(node, failure);
+    if (failure) throw failure;
+  }
+
+  /** Raise or clear the standing "this item isn't findable" issue for a node. */
+  async #recordIndexOutcome(node, failure) {
+    if (!this.issues) return;
+    try {
+      if (!failure) {
+        await this.issues.clear('index', node.id);
+        return;
+      }
+      await this.issues.raise({
+        kind: 'index',
+        subject: node.id,
+        collectionId: node.collectionId,
+        title: `“${node.name}” could not be indexed — it won't turn up in search`,
+        detail: failure.message || String(failure),
+        retry: { op: 'reindex-node', nodeId: node.id },
+      });
+    } catch (err) {
+      // The issue store failing is not a reason to fail the write that triggered it.
+      console.error('could not record an indexing issue:', err.message);
+    }
+  }
+
+  /**
+   * Re-index just the NAME of a node. Split out from `indexNode` because a rename
+   * changes nothing about the content: re-running every content indexer (re-reading the
+   * blob, re-embedding it) to correct one keyword document would make renaming a file
+   * as expensive as uploading it.
+   */
+  async reindexName(node) {
+    if (this.search) await this.search.indexName(node);
+  }
+
+  /**
+   * Re-index a node by id — the retry behind an indexing issue, and the full-content
+   * counterpart to `reindexName`.
+   */
+  async reindexNode(nodeId) {
+    const node = await this.metadata.getById(nodeId);
+    if (!node) throw TroveError.notFound('Item');
+    await this.indexNode(node);
+    return { ok: true };
+  }
+
+  /** Build the context an indexer gets: capped reads + a time-limited read URL. */
+  #indexCtx(node, storage) {
+    // No Range on an object that already fits: a 0-byte file has no satisfiable range at
+    // all, and asking for one made every empty file permanently un-indexable — a standing
+    // issue whose Retry button re-ran the identical failure forever.
+    const readRange = () => (node.size > this.maxIndexBytes
+      ? storage.get(node.storageKey, { range: { start: 0, end: this.maxIndexBytes - 1 } })
+      : storage.get(node.storageKey));
+    return {
+      node: { id: node.id, name: node.name, collectionId: node.collectionId, size: node.size, contentType: node.contentType },
+      maxBytes: this.maxIndexBytes,
+      readBytes: async () => readAll((await readRange()).stream),
+      readText: async () => new TextDecoder().decode(await readAll((await readRange()).stream)),
+      // A time-limited URL a remote/isolated indexer can fetch the bytes from. S3-class
+      // backends presign; everything else gets a URL this server signed. Either way it
+      // must be ABSOLUTE — whoever receives it is not in this browser and not on this
+      // box, so a relative URL would be a link to nowhere.
+      presignRead: async ({ expiresIn } = {}) => {
+        if (!this.mintUrl) throw TroveError.unsupported('This server cannot mint read URLs for indexers');
+        const { url } = await this.mintUrl(node.id, { op: 'index', expiresIn, absolute: true });
+        return url;
+      },
+    };
+  }
+
+  /**
+   * Run a single indexer against a node and apply its contribution. One misbehaving
+   * indexer must not stop the others, so the error is returned rather than thrown —
+   * the caller decides whether the node as a whole counts as failed.
+   * @returns {Promise<Error|null>}
+   */
+  async #runOneIndexer(indexer, node, ctx) {
+    try {
+      const contribution = await indexer.index(node, ctx ?? this.#indexCtx(node, await this.storageFor(node.collectionId)));
+      await this.#applyContribution(node.id, indexer.id, contribution);
+      return null;
+    } catch (err) {
+      console.error(`indexer ${indexer.id} failed on ${node.name}:`, err.message);
+      return err;
+    }
+  }
+
+  /**
+   * Re-run one indexer over every file it matches (e.g. right after an indexer is
+   * installed/enabled). Walks the metadata store in pages so a large drive doesn't
+   * load at once. Returns how many nodes it contributed to.
+   */
+  async backfillIndexer(indexer, { limit = Infinity, pageSize = 200 } = {}) {
+    let done = 0;
+    let afterId = null;
+    while (done < limit) {
+      const files = await this.metadata.scanItems({ afterId, limit: Math.min(pageSize, limit - done) });
+      if (!files.length) break;
+      for (const node of files) {
+        afterId = node.id;
+        let matches = false;
+        try { matches = indexer.match(node); } catch { matches = false; }
+        if (!matches) continue;
+        await this.#runOneIndexer(indexer, node);
+        done++;
+        if (done >= limit) break;
+      }
+      if (files.length < pageSize) break;
+    }
+    return { indexed: done };
+  }
+
+  /**
+   * Rebuild the whole search index from the drive's contents.
+   *
+   * The search index is derived state — every document in it can be recomputed from
+   * the file it came from — so losing it is recoverable, but only if something
+   * actually recovers it. This is that something: the server calls it at startup when
+   * a non-empty drive meets an empty index (a store that was in-memory, a dropped
+   * vector table after an embedding change, a restore from a metadata-only backup).
+   *
+   * Every file is re-read and every matching indexer re-run, so this is proportional
+   * to the drive, not to what changed. It pages, tolerates a per-file failure, and
+   * takes an `onProgress` so a caller can report on a long rebuild instead of going
+   * quiet.
+   *
+   * `shouldStop` exists because a rebuild outlives the request that started it: a
+   * server shutting down mid-rebuild would otherwise fail on every remaining file
+   * against a closing database, turning one event into a page of errors. Stopping is
+   * safe — the index is still empty, so the next start simply rebuilds it again.
+   *
+   * @param {{pageSize?: number, onProgress?: Function, shouldStop?: () => boolean}} [opts]
+   */
+  async reindexAll({ pageSize = 200, onProgress, shouldStop } = {}) {
+    // Ask for a total so progress can be honest about how far along it is. A store that
+    // can't count leaves this null, and the caller shows an indeterminate indicator —
+    // which is the right answer. Inventing a total would produce a progress bar that
+    // lies, and that is worse than a spinner.
+    const total = await this.metadata.countItems?.().catch(() => null) ?? null;
+    let indexed = 0;
+    let failed = 0;
+    let afterId = null;
+    let stopped = false;
+    onProgress?.({ indexed, failed, total });
+    outer: for (;;) {
+      const files = await this.metadata.scanItems({ afterId, limit: pageSize });
+      if (!files.length) break;
+      for (const node of files) {
+        if (shouldStop?.()) { stopped = true; break outer; }
+        afterId = node.id;
+        try {
+          await this.indexNode(node);
+          indexed++;
+        } catch (err) {
+          failed++;
+          console.error(`reindex failed for ${node.name}:`, err.message);
+        }
+      }
+      onProgress?.({ indexed, failed, total });
+      if (files.length < pageSize) break;
+    }
+    const result = { indexed, failed, stopped, total };
+    await this.#recordScanOutcome(result);
+    return result;
+  }
+
+  /**
+   * A scan that couldn't index everything is a standing problem about the DRIVE, not
+   * about any one file: search is incomplete and the user has no way to know unless
+   * we say so. Cleared by the next clean scan — which is what makes the retry button
+   * on it meaningful.
+   */
+  async #recordScanOutcome({ indexed, failed, stopped }) {
+    if (!this.issues) return;
+    try {
+      if (!failed && !stopped) {
+        await this.issues.clear('reindex');
+        return;
+      }
+      if (stopped) return; // interrupted by shutdown; the next start picks it up
+      await this.issues.raise({
+        kind: 'reindex',
+        title: `${failed} item${failed === 1 ? '' : 's'} could not be indexed — search is incomplete`,
+        detail: `${indexed} indexed, ${failed} failed. Individual items are listed separately where they could be identified.`,
+        retry: { op: 'reindex-all' },
+      });
+    } catch (err) {
+      console.error('could not record a reindex issue:', err.message);
+    }
+  }
+
+  /**
+   * Remove one contributor's contributions from every node (e.g. on uninstall).
+   *
+   * The search index is dropped in ONE bulk call — the stores can delete by indexer
+   * directly, so paging every node just to clear it per-node would be the same work
+   * done N times. Metadata still has to be walked, since a contribution lives on the
+   * node record.
+   */
+  async purgeIndexer(contributorId, { pageSize = 500 } = {}) {
+    if (this.search) await this.search.removeIndexer(contributorId).catch(() => {});
+    let cleared = 0;
+    let afterId = null;
+    for (;;) {
+      const files = await this.metadata.scanItems({ afterId, limit: pageSize });
+      if (!files.length) break;
+      for (const node of files) {
+        afterId = node.id;
+        if (node.contributions && node.contributions[contributorId]) {
+          await this.metadata.clearContribution(node.id, contributorId);
+          cleared++;
+        }
+      }
+      if (files.length < pageSize) break;
+    }
+    return { cleared };
+  }
+}
+

package/packages/core/src/issues.js

@@ -0,0 +1,150 @@
+// IssueRegistry — standing problems: something that was expected to happen didn't, and
+// is still not fixed.
+//
+// This is the counterpart to TaskRegistry, and the split between them is by LIFETIME:
+//
+//   Task   in-flight, ephemeral, per-process. "A reindex is running."
+//   Issue  standing, durable, outlives the process. "welcome.md failed to index."
+//
+// The distinction matters because of how these fail. A task that dies with its process
+// is correctly forgotten — it isn't running any more. But a file that failed to index
+// is *still* unindexed after a restart, and a console line that scrolled away three
+// deploys ago is not a record of that. So issues go in the KeyValueStore, which is
+// durable whenever the drive is.
+//
+// Three properties make this a registry rather than a log:
+//
+//   1. Keyed by (kind, subject), so raising the same problem twice UPDATES it. A file
+//      that fails to index on every retry is one issue with a count, not fifty rows.
+//   2. Cleared by the success that fixes it — `clear('index', nodeId)` on a successful
+//      index. An issue list nobody can empty gets ignored, and then it's just a log.
+//   3. Carries a declarative `retry` descriptor, so the thing that reports the problem
+//      also says how to attempt the fix. Most standing problems are retryable; one that
+//      makes the user go find the right button is only half-reported.
+
+import { TroveError } from './errors.js';
+
+const NS = 'issues';
+/** Bounded: a systemic failure (storage down mid-reindex) must not fill the store. */
+const MAX_ISSUES = 500;
+
+/** A stable, human-readable id. Clients must encodeURIComponent it for a path segment. */
+export function issueId(kind, subject) {
+  return subject ? `${kind}:${subject}` : kind;
+}
+
+export class IssueRegistry {
+  /**
+   * @param {{kv: import('./kv.js').KeyValueStore, now?: () => number}} deps
+   */
+  constructor({ kv, now = () => Date.now() } = {}) {
+    if (!kv) throw TroveError.invalid('IssueRegistry needs a KeyValueStore');
+    this.kv = kv;
+    this.now = now;
+    this._handlers = new Map(); // retry op -> (issue) => Promise
+  }
+
+  /**
+   * Register how to retry one class of issue. Kept as a registration rather than a
+   * switch inside this class so core doesn't need to know what a reindex is — the
+   * server, which owns the Vfs, supplies the verbs.
+   *
+   * @param {string} op
+   * @param {(issue: object) => Promise<any>} handler
+   */
+  handle(op, handler) {
+    this._handlers.set(op, handler);
+  }
+  canRetry(issue) {
+    return !!(issue?.retry?.op && this._handlers.has(issue.retry.op));
+  }
+
+  /**
+   * Record (or refresh) a standing problem.
+   *
+   * @param {object} spec
+   * @param {string} spec.kind          'index', 'reindex', 'upload' — the class of problem
+   * @param {string} [spec.subject]     what it is about (a node id); omit for drive-wide
+   * @param {string} spec.title         one line, in the user's terms
+   * @param {string} [spec.detail]      the underlying error, for someone who wants it
+   * @param {string} [spec.severity]    'error' (default) | 'warning'
+   * @param {string} [spec.collectionId] scopes visibility; null = drive-wide (admin)
+   * @param {{op: string}} [spec.retry] declarative retry, executed by a registered handler
+   */
+  async raise(spec) {
+    if (!spec?.kind || !spec?.title) throw TroveError.invalid('An issue needs a kind and a title');
+    const id = issueId(spec.kind, spec.subject);
+    const existing = await this.kv.get(NS, id);
+    const at = this.now();
+    const issue = {
+      id,
+      kind: spec.kind,
+      subject: spec.subject ?? null,
+      title: spec.title,
+      detail: spec.detail ?? null,
+      severity: spec.severity || 'error',
+      collectionId: spec.collectionId ?? null,
+      retry: spec.retry ?? null,
+      // Keep the FIRST sighting: "failing since 09:14" is the useful fact, and it would
+      // be lost if every recurrence reset the clock.
+      firstAt: existing?.firstAt ?? at,
+      lastAt: at,
+      count: (existing?.count ?? 0) + 1,
+    };
+    await this.kv.set(NS, id, issue);
+    if (!existing) await this.#enforceCap();
+    return issue;
+  }
+
+  /** Remove the issue for (kind, subject) — call this on the success that resolves it. */
+  async clear(kind, subject) {
+    await this.kv.delete(NS, issueId(kind, subject));
+  }
+
+  async get(id) {
+    return this.kv.get(NS, id);
+  }
+  async remove(id) {
+    await this.kv.delete(NS, id);
+  }
+
+  /**
+   * @param {{collectionIds?: string[], includeGlobal?: boolean, limit?: number}} [opts]
+   *   `collectionIds` restricts to issues about collections the caller can read. A
+   *   drive-wide issue (collectionId null) is only for someone allowed the whole drive,
+   *   because its title can name things a scoped reader shouldn't learn about.
+   */
+  async list({ collectionIds, includeGlobal = true, limit = 100 } = {}) {
+    const rows = await this.kv.list(NS, '');
+    return rows
+      .map((r) => r.value)
+      .filter(Boolean)
+      .filter((i) => (i.collectionId == null ? includeGlobal : !collectionIds || collectionIds.includes(i.collectionId)))
+      .sort((a, b) => b.lastAt - a.lastAt)
+      .slice(0, limit);
+  }
+
+  /**
+   * Attempt the fix this issue describes. The issue is NOT cleared here — it is cleared
+   * by whatever succeeds, so a retry that reports success while the underlying problem
+   * persists can't quietly hide it.
+   */
+  async retry(id) {
+    const issue = await this.get(id);
+    if (!issue) throw TroveError.notFound('Issue');
+    const handler = this._handlers.get(issue.retry?.op);
+    if (!handler) throw TroveError.invalid('This problem cannot be retried automatically');
+    return handler(issue);
+  }
+
+  async #enforceCap() {
+    const rows = await this.kv.list(NS, '');
+    if (rows.length <= MAX_ISSUES) return;
+    const oldest = rows
+      .map((r) => r.value)
+      .filter(Boolean)
+      .sort((a, b) => a.lastAt - b.lastAt)
+      .slice(0, rows.length - MAX_ISSUES);
+    for (const issue of oldest) await this.kv.delete(NS, issue.id);
+  }
+}

package/packages/core/src/links.js

@@ -0,0 +1,141 @@
+// `trove:` — the URI that addresses an ITEM in the drive.
+//
+// There is no folder hierarchy. A collection is a flat namespace of uniquely-named
+// items, and structure comes from items linking to each other — a markdown document
+// that links its sources is what a folder used to be, except it can say *why* things
+// belong together, an item can appear in several of them, and the grouping is
+// searchable content rather than an invisible container.
+//
+// So a link has to be something a person can type into a markdown file:
+//
+//   trove:default?name=sailing.txt      canonical, by name
+//   trove:default/sailing.txt           shorthand for the same thing
+//   trove:default?id=fil_01H2X8F4KQ     by id — survives a rename, unreadable
+//
+// The selector is EXPLICIT (`?name=` vs `?id=`) rather than inferred from the shape
+// of the segment: a name that happens to look like an id would otherwise resolve to
+// something else entirely, and a link that silently retargets is worse than one that
+// visibly breaks. The `/name` shorthand is unambiguous for the same reason — that
+// slot only ever means a name.
+//
+// Names are unique per collection, which is what makes `?name=` resolve to exactly one
+// item. Renaming therefore breaks inbound links, on purpose and visibly: the alternative
+// is opaque ids nobody can hand-write, which would put linking back in the UI's hands.
+// `?id=` is there for links a tool inserts, where stability matters more than legibility.
+
+import { TroveError } from './errors.js';
+
+export const TROVE_SCHEME = 'trove:';
+
+// An item name is capped at 255 chars (isValidItemName), so a longer selector can never
+// resolve to anything. Refusing it at parse time keeps garbage out of the links index
+// rather than storing kilobytes that will never match.
+const MAX_SELECTOR = 255;
+// How many distinct links one item may record. A document is a grouping, not a database
+// dump; past this the value is in the search index, not the link graph.
+export const MAX_LINKS_PER_ITEM = 500;
+
+// Collection ids are slugs (see CollectionService); a name is anything but a slash,
+// since the pathname shorthand has to stop somewhere.
+const COLLECTION_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+
+/**
+ * Parse a `trove:` URI into `{ collection, by: 'name'|'id', value }`, or null if it
+ * isn't one. Never throws — callers parse untrusted document text with this, where a
+ * malformed link is a thing to render as broken, not an exception.
+ */
+export function parseTroveUri(uri) {
+  if (typeof uri !== 'string' || !uri.toLowerCase().startsWith(TROVE_SCHEME)) return null;
+  let url;
+  try {
+    url = new URL(uri);
+  } catch {
+    return null;
+  }
+  // `trove:default/sailing.txt` → pathname "default/sailing.txt"; the slash-free case
+  // is `trove:default?name=…`, where the whole pathname is the collection.
+  const path = url.pathname;
+  const slash = path.indexOf('/');
+  const collection = slash < 0 ? path : path.slice(0, slash);
+  if (!COLLECTION_RE.test(collection)) return null;
+
+  const id = url.searchParams.get('id');
+  const name = url.searchParams.get('name');
+  let shorthand = '';
+  if (slash >= 0) {
+    // A malformed percent-escape is a malformed link, not an exception to propagate
+    // out of a document render.
+    try { shorthand = decodeURIComponent(path.slice(slash + 1)); } catch { return null; }
+  }
+
+  // Both selectors at once is a contradiction, not something to silently pick between.
+  if (id != null && (name != null || shorthand)) return null;
+  const by = id != null ? 'id' : 'name';
+  const value = id != null ? id : (name != null ? name : shorthand);
+  if (!value || value.length > MAX_SELECTOR) return null;
+  return { collection, by, value };
+}
+
+/** Whether `uri` is a well-formed trove: reference. */
+export function isTroveUri(uri) {
+  return parseTroveUri(uri) != null;
+}
+
+/**
+ * Build a `trove:` URI. `by` defaults to 'name' — the legible form, which is what
+ * gets written into documents; pass 'id' for a link that must survive a rename.
+ */
+export function troveUri(node, by = 'name') {
+  const collection = node?.collectionId || 'default';
+  if (by === 'id') {
+    if (!node?.id) throw TroveError.invalid('trove: link by id needs a node id');
+    return `${TROVE_SCHEME}${collection}?id=${encodeURIComponent(node.id)}`;
+  }
+  if (!node?.name) throw TroveError.invalid('trove: link by name needs a node name');
+  return `${TROVE_SCHEME}${collection}?name=${encodeURIComponent(node.name)}`;
+}
+
+/**
+ * Every distinct `trove:` reference in a block of text, in first-appearance order.
+ *
+ * Deliberately scans raw text rather than parsing markdown: a link is just as real in
+ * an HTML `href`, a bare mention, or a front-matter list, and the point of extraction
+ * is to know what an item references — not to reproduce one renderer's idea of a link.
+ * Trailing punctuation is trimmed so `see trove:default/a.md.` doesn't capture the dot.
+ */
+export function extractTroveLinks(text, { limit = MAX_LINKS_PER_ITEM } = {}) {
+  if (typeof text !== 'string' || !text) return [];
+  const out = [];
+  const seen = new Set();
+  // Stop at whitespace and at the delimiters that wrap a URL in markdown/HTML.
+  const re = /trove:[^\s<>"'`)\]}]+/gi;
+  for (const m of text.matchAll(re)) {
+    if (out.length >= limit) break;
+    const raw = m[0].replace(/[.,;:!?]+$/, '');
+    const parsed = parseTroveUri(raw);
+    if (!parsed) continue;
+    const canonical = `${TROVE_SCHEME}${parsed.collection}?${parsed.by}=${encodeURIComponent(parsed.value)}`;
+    if (seen.has(canonical)) continue;
+    seen.add(canonical);
+    out.push({ uri: canonical, raw, ...parsed });
+  }
+  return out;
+}
+
+/**
+ * The canonical form of a reference, for storing and comparing. Two links that address
+ * the same item by the same selector must produce the same string, or backlinks would
+ * miss `trove:default/a.md` when the target stored `trove:default?name=a.md`.
+ */
+export function canonicalTroveUri(uri) {
+  const p = parseTroveUri(uri);
+  return p ? `${TROVE_SCHEME}${p.collection}?${p.by}=${encodeURIComponent(p.value)}` : null;
+}
+
+/** Both canonical forms an item can be addressed by — what a backlink query looks for. */
+export function troveUrisFor(node) {
+  const out = [];
+  if (node?.collectionId && node?.name) out.push(troveUri(node, 'name'));
+  if (node?.collectionId && node?.id) out.push(troveUri(node, 'id'));
+  return out;
+}