orama-db: `orama-db.json` changes on every build

Start with packages/react/src/orama-db/generate.mjs: read how it builds documents, calls insertMultiple, and saves the index; the issue also points to useOrama.mjs to check how search uses results. Add stable ids and sort the flattened documents by href, then create the suggested generator tests for repeatability, input order, and search behavior. Run node --run test and confirm the generated output is stable; pull request #1190 is already open against this issue.

Running a build twice on the same docs gives two different orama-db.json files, for two reasons:

1. Timestamp-based ids. The orama-db generator inserts documents without an id, so Orama 3.x makes one up from the current time and a counter (e.g. 20003290-1). That id is saved in the index (internalDocumentIDStore.internalIdToId), so the file changes on every build.
2. Insertion order. Orama's saved index follows the order documents were inserted, and the generator's input order can change between builds (see #1183).

The search index is several MB, so a file that changes on every deploy wastes caching, and CI can't compare it byte for byte.

Where to look

• packages/react/src/orama-db/generate.mjs:27-44: builds the documents (title, description, href, siteSection) with no id, in input order.
• The same file, line 40: href (${entry.path}.html#${entry.heading.data.slug}), which makes a natural stable id.
• The same file, line 47: insertMultiple(db, documents); lines 49-56: save(db) is written to orama-db.json.
• packages/react/src/html/ui/hooks/useOrama.mjs:26-41: the website loads the saved index and searches it. It doesn't depend on the id format, and results are rendered from hit.document.

How to reproduce

From packages/react (where @orama/orama resolves), save this as repro.mjs and run node repro.mjs a few times:

import { createHash } from 'node:crypto';
import { create, insertMultiple, save } from '@orama/orama';

const docs = [
  { title: 'fs', description: 'File system', href: 'fs.html#fs', siteSection: 'fs' },
  { title: 'fs > readFile', description: 'Reads a file', href: 'fs.html#readfile', siteSection: 'fs' },
];

const db = create({
  schema: { title: 'string', description: 'string', href: 'string', siteSection: 'string' },
});

await insertMultiple(db, docs); // try: docs.map(doc => ({ id: doc.href, ...doc }))

const out = JSON.stringify(save(db));
console.log(createHash('sha256').update(out).digest('hex').slice(0, 16));

Each run prints a different hash. With the commented id: doc.href line, every run prints the same one, until you reverse docs, which changes it again.

Suggested approach

Only packages/react/src/orama-db/generate.mjs needs to change:

1. Add id: href to each document (Orama requires string ids, and href is one).
2. Sort the flattened documents by href before inserting them, comparing with < and > (or localeCompare(..., 'en')) so the order doesn't depend on the machine's locale.

Keep the existing flatMap as it is, and sort its result, not the input: buildHierarchicalTitle walks each module's headings in document order to build titles like "Class > Method".

How to test

There's no generator test for orama-db yet. Create packages/react/src/orama-db/__tests__/generate.test.mjs, setting up the config like llms-txt-full/__tests__/generate.test.mjs does (setConfig({ target: ['orama-db'] }), then set output to undefined so generate() just returns the saved index). With a few fake metadata entries from two modules, test that:

1. Two runs give the same output: compare the JSON.stringify of two generate() results. This already fails today within a single process.
2. Input order doesn't matter: put one module's entries before the other's, keeping each module's own entries in order, and compare.
3. Search still works: load() the result into create({ schema: {} }), search() for a title word, and check hits[0].document.href.

Run everything with node --run test.

Things to watch out for

• Ids must be unique, or Orama throws DOCUMENT_ALREADY_EXISTS and the build fails. Slugs are deduplicated per file, so hrefs should be unique. If the full Node.js docs build throws anyway, point out the duplicate in your PR rather than going back to automatic ids.
• save() doesn't include the database's own id, so that one doesn't matter.
• The output is only identical for the same @orama/orama version; a dependency update can still change it.

Getting started

New to doc-kit? CONTRIBUTING.md covers setup, running the tests and adding a changeset (node --run changeset, a patch for @doc-kit/generator-react). Leave a comment here if you'd like to take it on.