@wxxb789/anc 0.0.1

package/src/lib/snapshot-contract.js

@@ -0,0 +1,216 @@
+/**
+ * The snapshot's exact schema contract, over a row-reader rather than a driver.
+ *
+ * Both drivers that can open a snapshot — the native build reader and the
+ * browser WASM reader — must accept and reject the same files. Expressing the
+ * check as "run these SQL statements and give me rows" lets one implementation
+ * serve both without either importing the other; `scripts/write-snapshot.ts`
+ * adapts `node:sqlite`, and the browser Worker adapts the WASM connection.
+ *
+ * The check is deliberately not satisfied by the header constants: a file can
+ * carry the right `application_id` and `user_version` and still have an
+ * unexpected column type, dropped `NOT NULL`, foreign key, `STRICT`/
+ * `WITHOUT ROWID` option, `CHECK`, or explicit index — added, removed, or
+ * reshaped (columns, uniqueness, partiality) — and a query against it would then
+ * return something whose meaning differs from the contract.
+ *
+ * Every statement issued here is a read-only `PRAGMA` or `sqlite_schema`
+ * query, so the reader can stay read-only. `CHECK` clauses are the one
+ * declaration SQLite exposes only in the stored DDL text; they are matched
+ * after case and whitespace folding, which is stable because the writer
+ * applies `SNAPSHOT_SCHEMA_SQL` verbatim.
+ */
+import { SNAPSHOT_APPLICATION_ID, SNAPSHOT_EXPLICIT_INDEX, SNAPSHOT_TABLE_SHAPES, SNAPSHOT_TABLES, SNAPSHOT_USER_VERSION, } from "./snapshot.js";
+/** Collapse case and whitespace so stored DDL compares by clause, not layout. */
+function foldSql(sql) {
+    return sql.replace(/\s+/g, ' ').trim().toUpperCase();
+}
+/** `from -> table.to`, so foreign keys compare as a set, not in pragma order. */
+function foreignKeyText(key) {
+    return `${key.from} -> ${key.table}.${key.to}`;
+}
+/** Order foreign keys by their printed form; `PRAGMA` order is not stable. */
+function byForeignKeyText(left, right) {
+    const leftText = foreignKeyText(left);
+    const rightText = foreignKeyText(right);
+    return leftText < rightText ? -1 : leftText > rightText ? 1 : 0;
+}
+/** Fail unless `PRAGMA table_info` matches the declared columns exactly. */
+function assertColumns(read, table, columns) {
+    const actual = read(`PRAGMA table_info(${table})`);
+    if (actual.length !== columns.length) {
+        throw new Error(`snapshot table ${table} has columns [${actual.map((row) => String(row['name'])).join(', ')}], ` +
+            `expected [${columns.map((column) => column.name).join(', ')}]`);
+    }
+    for (const [index, column] of columns.entries()) {
+        const row = actual[index];
+        const actualText = `name=${String(row['name'])} type=${String(row['type'])} ` +
+            `notnull=${String(row['notnull'])} pk=${String(row['pk'])}`;
+        const expectedText = `name=${column.name} type=${column.type} ` +
+            `notnull=${column.notNull ? 1 : 0} pk=${column.pk}`;
+        if (actualText !== expectedText) {
+            throw new Error(`snapshot table ${table} column ${index + 1} is ${actualText}, expected ${expectedText}`);
+        }
+    }
+}
+/** Fail unless `PRAGMA table_list` reports the declared kind and options. */
+function assertTableOptions(listed, table, shape) {
+    const row = listed.find((candidate) => candidate['name'] === table);
+    if (row === undefined)
+        throw new Error(`snapshot table ${table} is absent from PRAGMA table_list`);
+    const kind = String(row['type']);
+    if (kind !== 'table') {
+        throw new Error(`snapshot table ${table} is a ${kind}, expected an ordinary table`);
+    }
+    const strict = Number(row['strict']) === 1;
+    if (strict !== shape.strict) {
+        throw new Error(`snapshot table ${table} is ${strict ? 'STRICT' : 'not STRICT'}, ` +
+            `expected ${shape.strict ? 'STRICT' : 'not STRICT'}`);
+    }
+    const withoutRowid = Number(row['wr']) === 1;
+    if (withoutRowid !== shape.withoutRowid) {
+        throw new Error(`snapshot table ${table} is ${withoutRowid ? 'WITHOUT ROWID' : 'a rowid table'}, ` +
+            `expected ${shape.withoutRowid ? 'WITHOUT ROWID' : 'a rowid table'}`);
+    }
+}
+/** Fail unless `PRAGMA foreign_key_list` matches the declared references. */
+function assertForeignKeys(read, table, expected) {
+    const actual = read(`PRAGMA foreign_key_list(${table})`)
+        .map((row) => ({ from: String(row['from']), table: String(row['table']), to: String(row['to']) }))
+        .sort(byForeignKeyText);
+    const wanted = expected.map((key) => ({ ...key })).sort(byForeignKeyText);
+    const actualText = actual.map(foreignKeyText);
+    const wantedText = wanted.map(foreignKeyText);
+    if (actualText.join(',') !== wantedText.join(',')) {
+        throw new Error(`snapshot table ${table} has foreign keys [${actualText.join(', ')}], ` +
+            `expected [${wantedText.join(', ')}]`);
+    }
+}
+/** Fail unless every declared `CHECK` clause survives in the stored DDL. */
+function assertChecks(storedSql, table, checks) {
+    const folded = foldSql(storedSql);
+    for (const check of checks) {
+        if (!folded.includes(foldSql(check))) {
+            throw new Error(`snapshot table ${table} is missing the ${check} constraint`);
+        }
+    }
+}
+/** Fail unless the one explicit secondary index matches its declared definition. */
+function assertExplicitIndex(read) {
+    const index = SNAPSHOT_EXPLICIT_INDEX;
+    const row = read(`PRAGMA index_list(${index.table})`).find((candidate) => candidate['name'] === index.name);
+    if (row === undefined) {
+        throw new Error(`snapshot table ${index.table} is missing the ${index.name} index`);
+    }
+    const unique = Number(row['unique']) === 1;
+    if (unique !== index.unique) {
+        throw new Error(`snapshot index ${index.name} is ${unique ? 'unique' : 'not unique'}, ` +
+            `expected ${index.unique ? 'unique' : 'not unique'}`);
+    }
+    const partial = Number(row['partial']) === 1;
+    if (partial !== index.partial) {
+        throw new Error(`snapshot index ${index.name} is ${partial ? 'partial' : 'full'}, ` +
+            `expected ${index.partial ? 'partial' : 'full'}`);
+    }
+    const columns = read(`PRAGMA index_info(${index.name})`)
+        .map((info) => ({ seqno: Number(info['seqno']), name: String(info['name']) }))
+        .sort((left, right) => left.seqno - right.seqno)
+        .map((info) => info.name);
+    if (columns.join(',') !== index.columns.join(',')) {
+        throw new Error(`snapshot index ${index.name} is on [${columns.join(', ')}], expected [${index.columns.join(', ')}]`);
+    }
+}
+/**
+ * Fail unless every declared `UNIQUE` constraint survives as exactly one
+ * implicit index, matched by its indexed columns.
+ *
+ * SQLite names these `sqlite_autoindex_*` and the reader query filters every
+ * `sqlite_` name out, so this is the only check that sees them: an added
+ * `UNIQUE (node_id, tag_id)` — the reverse membership index the accepted
+ * design forbids — appears here as an extra origin-`u` row and fails closed.
+ * Matched by columns rather than name because SQLite generates the names.
+ */
+function assertUniqueIndexes(read, table, expected) {
+    const actual = read(`PRAGMA index_list(${table})`)
+        .filter((row) => String(row['origin']) === 'u')
+        .map((row) => {
+        const name = String(row['name']);
+        const columns = read(`PRAGMA index_info(${name})`)
+            .map((info) => ({ seqno: Number(info['seqno']), name: String(info['name']) }))
+            .sort((left, right) => left.seqno - right.seqno)
+            .map((info) => info.name)
+            .join(',');
+        return columns;
+    })
+        .sort();
+    const wanted = [...expected].sort();
+    if (actual.join('|') !== wanted.join('|')) {
+        const printed = (sets) => sets.map((set) => `(${set})`).join(', ');
+        throw new Error(`snapshot table ${table} has implicit unique indexes on [${printed(actual)}], ` +
+            `expected [${printed(wanted)}]`);
+    }
+}
+/**
+ * Fail unless the connection carries exactly the accepted schema.
+ *
+ * @param read A function that executes one SQL statement on the imported
+ *   snapshot. It must not write. `PRAGMA` statements and reads only.
+ * @throws {Error} naming the first discrepancy, so a mismatch fails closed.
+ */
+export function assertSnapshotRows(read) {
+    const applicationId = read('PRAGMA application_id')[0]?.['application_id'];
+    if (applicationId !== SNAPSHOT_APPLICATION_ID) {
+        throw new Error(`snapshot application_id is ${String(applicationId)}, expected ${SNAPSHOT_APPLICATION_ID}`);
+    }
+    const userVersion = read('PRAGMA user_version')[0]?.['user_version'];
+    if (userVersion !== SNAPSHOT_USER_VERSION) {
+        throw new Error(`snapshot user_version is ${String(userVersion)}, expected ${SNAPSHOT_USER_VERSION}`);
+    }
+    const objects = read("SELECT type, name, sql FROM sqlite_schema WHERE name NOT LIKE 'sqlite\\_%' ESCAPE '\\' ORDER BY type, name");
+    const tables = objects
+        .filter((row) => row['type'] === 'table')
+        .map((row) => String(row['name']))
+        .sort();
+    const expectedTables = [...SNAPSHOT_TABLES].sort();
+    if (tables.join(',') !== expectedTables.join(',')) {
+        throw new Error(`snapshot tables are [${tables.join(', ')}], expected [${SNAPSHOT_TABLES.join(', ')}]`);
+    }
+    // `sqlite_schema` hides the UNIQUE constraints' implicit `sqlite_` indexes
+    // behind the query's name filter, so the index rows that remain are exactly
+    // the explicitly created ones. The filter matches `sqlite_` literally — the
+    // underscore is escaped, because an unescaped LIKE `_` is a wildcard and
+    // would also hide a user-creatable name such as `sqliteX`. This must equal
+    // the one accepted index: an added explicit reverse membership index, a
+    // renamed accepted index, or a missing accepted index each change the storage
+    // contract. `assertExplicitIndex` below still checks that index's declared
+    // shape, and `assertUniqueIndexes` checks the implicit indexes this filter
+    // hides, so a added `UNIQUE` constraint cannot slip through either spelling.
+    const indexes = objects
+        .filter((row) => row['type'] === 'index')
+        .map((row) => String(row['name']))
+        .sort();
+    const expectedIndexes = [SNAPSHOT_EXPLICIT_INDEX.name];
+    if (indexes.join(',') !== expectedIndexes.join(',')) {
+        throw new Error(`snapshot explicit indexes are [${indexes.join(', ')}], expected [${expectedIndexes.join(', ')}]`);
+    }
+    const otherObjects = objects.filter((row) => row['type'] !== 'table' && row['type'] !== 'index');
+    if (otherObjects.length > 0) {
+        throw new Error(`snapshot carries unexpected schema objects: ${otherObjects
+            .map((row) => `${String(row['type'])} ${String(row['name'])}`)
+            .join(', ')}`);
+    }
+    // The stored DDL is the only place a CHECK clause survives; the table-list
+    // pragma is the only place STRICT/WITHOUT ROWID survive.
+    const storedSql = new Map(objects
+        .filter((row) => row['type'] === 'table')
+        .map((row) => [String(row['name']), String(row['sql'] ?? '')]));
+    const listed = read('PRAGMA table_list');
+    for (const [table, shape] of Object.entries(SNAPSHOT_TABLE_SHAPES)) {
+        assertColumns(read, table, shape.columns);
+        assertTableOptions(listed, table, shape);
+        assertForeignKeys(read, table, shape.foreignKeys);
+        assertChecks(storedSql.get(table) ?? '', table, shape.checks);
+        assertUniqueIndexes(read, table, shape.uniqueConstraints);
+    }
+    assertExplicitIndex(read);
+}

package/src/lib/snapshot-operations.js

@@ -0,0 +1,147 @@
+/**
+ * The named snapshot operations, over a minimal row-reader adapter.
+ *
+ * One implementation serves the browser Worker and any native caller: the
+ * adapter only has to run a fixed SQL string with bound parameters and return
+ * rows. The semantics are `docs/core-design/sqlite-contract.md`'s: cursor
+ * pagination continues after the last returned slug, graph selection precedes
+ * induced-edge extraction, and graph degree counts distinct adjacent notes.
+ */
+import { SNAPSHOT_QUERIES, normalizePageSize, pageOf, } from "./snapshot-queries.js";
+import { rankGlobal, inducedEdges, selectLocal, GLOBAL_NODE_LIMIT } from "./graph-selection.js";
+function summary(row) {
+    return selectionSummary(selectionNode(row));
+}
+function slugOf(db, slug) {
+    const row = db.select(SNAPSHOT_QUERIES.nodeBySlug, [slug])[0];
+    return row === undefined ? undefined : Number(row['id']);
+}
+/** Preview one published note, or `null` for an unknown or withheld slug. */
+export function preview(db, slug) {
+    const node = db.select(SNAPSHOT_QUERIES.previewNode, [slug])[0];
+    if (node === undefined)
+        return null;
+    const aliases = db.select(SNAPSHOT_QUERIES.previewAliases, [Number(node['id'])]).map((row) => String(row['alias']));
+    return {
+        slug: String(node['slug']),
+        title: String(node['title']),
+        excerpt: String(node['excerpt']),
+        language: String(node['language']),
+        aliases,
+    };
+}
+/** One page of outgoing or backlinks for a known subject. */
+export function edgePage(db, direction, slug, cursor, pageSize) {
+    const id = slugOf(db, slug);
+    if (id === undefined)
+        return { known: false, page: { notes: [], nextCursor: null } };
+    const size = normalizePageSize(pageSize);
+    const first = direction === 'outgoing' ? SNAPSHOT_QUERIES.outgoingFirst : SNAPSHOT_QUERIES.backlinksFirst;
+    const after = direction === 'outgoing' ? SNAPSHOT_QUERIES.outgoingAfter : SNAPSHOT_QUERIES.backlinksAfter;
+    const rows = cursor === undefined || cursor === null
+        ? db.select(first, [id, size + 1])
+        : db.select(after, [id, cursor, size + 1]);
+    const { items, nextCursor } = pageOf(rows.map(summary), size);
+    return { known: true, page: { notes: items, nextCursor } };
+}
+/** One page of notes carrying a canonical tag, or an unknown-tag result. */
+export function tagPage(db, tagKey, cursor, pageSize) {
+    const tag = db.select(SNAPSHOT_QUERIES.tagByKey, [tagKey])[0];
+    if (tag === undefined)
+        return { known: false };
+    const size = normalizePageSize(pageSize);
+    const rows = cursor === undefined || cursor === null
+        ? db.select(SNAPSHOT_QUERIES.byTagFirst, [tagKey, size + 1])
+        : db.select(SNAPSHOT_QUERIES.byTagAfter, [tagKey, cursor, size + 1]);
+    const { items, nextCursor } = pageOf(rows.map(summary), size);
+    return { known: true, tag: { key: String(tag['key']), label: String(tag['label']) }, notes: items, nextCursor };
+}
+/** One node as the shared selection contract sees it. */
+function selectionNode(row) {
+    return {
+        id: Number(row['id']),
+        slug: String(row['slug']),
+        title: String(row['title']),
+        language: String(row['language']),
+    };
+}
+/**
+ * The directed edges whose two endpoints are all in `ids`.
+ *
+ * Bound placeholders, never interpolated data. This is the contract's "after
+ * choosing the displayed nodes, query all directed edges whose two endpoints
+ * belong to that set": scanning every edge in the corpus made a 10,000-note
+ * local graph O(corpus) per request and missed the warm target.
+ */
+function edgesAmongIds(db, ids) {
+    if (ids.length === 0)
+        return [];
+    const placeholders = ids.map(() => '?').join(',');
+    const sql = `SELECT s.slug AS source, t.slug AS target FROM edges AS e ` +
+        `JOIN nodes AS s ON s.id = e.source_id JOIN nodes AS t ON t.id = e.target_id ` +
+        `WHERE e.source_id IN (${placeholders}) AND e.target_id IN (${placeholders}) ` +
+        `ORDER BY source, target`;
+    return db.select(sql, [...ids, ...ids]).map((row) => ({
+        from: row.source,
+        to: row.target,
+    }));
+}
+/** The public summary of one selection node. */
+function selectionSummary(node) {
+    return { slug: node.slug, title: node.title, language: node.language };
+}
+/** `nodeDegrees`/`tagNodeDegrees` rows as the rank function's degree lookup. */
+function degreeMap(rows) {
+    return new Map(rows.map((row) => [Number(row['id']), Number(row['degree'])]));
+}
+/**
+ * The one-hop neighbourhood of a known center.
+ *
+ * The SQL `UNION` deduplicates incoming/outgoing and the shared selection
+ * contract sorts, limits, and extracts induced edges, so the Worker and the
+ * build cannot disagree about the drawn set.
+ */
+export function localGraph(db, slug) {
+    const center = db.select(SNAPSHOT_QUERIES.nodeBySlug, [slug])[0];
+    if (center === undefined)
+        return null;
+    const centerNode = selectionNode(center);
+    const neighbours = db
+        .select(SNAPSHOT_QUERIES.neighbors, [centerNode.id, centerNode.id])
+        .map(selectionNode);
+    // Choose the drawn set first, then read only the edges among it.
+    const preliminary = selectLocal(centerNode, neighbours, []);
+    const ids = [centerNode.id, ...preliminary.drawn.map((node) => node.id)];
+    const selected = new Set([centerNode.slug, ...preliminary.drawn.map((node) => node.slug)]);
+    return {
+        center: selectionSummary(centerNode),
+        nodes: preliminary.drawn.map(selectionSummary),
+        edges: inducedEdges(selected, edgesAmongIds(db, ids)),
+        omitted: preliminary.omitted,
+    };
+}
+/**
+ * The ranked global graph, optionally restricted to one tag's members.
+ *
+ * Ranking has one authority: `rankGlobal` orders by degree in the candidate
+ * graph, descending, then title/slug. The unfiltered case takes degrees from
+ * one aggregate over the edge set; the filtered case takes the tag's member
+ * rows and their in-tag degrees from tag-scoped statements, so filtering never
+ * pulls the corpus' edge rows into JS. Only after the drawn set is chosen are
+ * the directed edges among it read.
+ */
+export function globalGraph(db, tagKey) {
+    const filtered = tagKey !== undefined && tagKey !== null;
+    const candidates = db
+        .select(filtered ? SNAPSHOT_QUERIES.tagNodes : SNAPSHOT_QUERIES.allNodes, filtered ? [tagKey] : [])
+        .map(selectionNode);
+    const degrees = degreeMap(db.select(filtered ? SNAPSHOT_QUERIES.tagNodeDegrees : SNAPSHOT_QUERIES.nodeDegrees, filtered ? [tagKey] : []));
+    const ranked = rankGlobal(candidates, (node) => degrees.get(node.id) ?? 0);
+    const selected = ranked.slice(0, GLOBAL_NODE_LIMIT);
+    const selectedSlugs = new Set(selected.map((node) => node.slug));
+    return {
+        nodes: selected.map(selectionSummary),
+        edges: inducedEdges(selectedSlugs, edgesAmongIds(db, selected.map((node) => node.id))),
+        omitted: ranked.length - selected.length,
+    };
+}

package/src/lib/snapshot-queries.js

@@ -0,0 +1,216 @@
+/**
+ * Named query surface over the public snapshot.
+ *
+ * One module owns the fixed, parameterized SQL and the typed shape of every
+ * result, so the native build driver (`node:sqlite`) and the browser WASM driver
+ * run the same statements rather than two reconstructions that can disagree.
+ * Execution is the adapter's job; this file is SQL, row types, and the pure
+ * pagination/selection rules.
+ *
+ * `docs/core-design/sqlite-contract.md` owns the semantics, especially:
+ * pagination continues **after the last returned slug** and never from the
+ * lookahead row, and graph selection happens **before** induced-edge extraction.
+ */
+import { isNoteSlug } from "./route-path.js";
+/**
+ * Every statement the snapshot contract exposes. Named parameters are positional
+ * (`?`) rather than named because both drivers bind arrays identically and no
+ * statement needs the same value twice.
+ */
+export const SNAPSHOT_QUERIES = {
+    previewNode: `
+    SELECT id, slug, title, excerpt, language
+    FROM nodes
+    WHERE slug = ?`.trim(),
+    previewAliases: `
+    SELECT alias
+    FROM aliases
+    WHERE node_id = ?
+    ORDER BY ordinal`.trim(),
+    outgoingFirst: `
+    SELECT n.slug, n.title, n.language
+    FROM edges AS e
+    JOIN nodes AS n ON n.id = e.target_id
+    WHERE e.source_id = ?
+    ORDER BY n.slug
+    LIMIT ?`.trim(),
+    outgoingAfter: `
+    SELECT n.slug, n.title, n.language
+    FROM edges AS e
+    JOIN nodes AS n ON n.id = e.target_id
+    WHERE e.source_id = ? AND n.slug > ?
+    ORDER BY n.slug
+    LIMIT ?`.trim(),
+    backlinksFirst: `
+    SELECT n.slug, n.title, n.language
+    FROM edges AS e
+    JOIN nodes AS n ON n.id = e.source_id
+    WHERE e.target_id = ?
+    ORDER BY n.slug
+    LIMIT ?`.trim(),
+    backlinksAfter: `
+    SELECT n.slug, n.title, n.language
+    FROM edges AS e
+    JOIN nodes AS n ON n.id = e.source_id
+    WHERE e.target_id = ? AND n.slug > ?
+    ORDER BY n.slug
+    LIMIT ?`.trim(),
+    tagByKey: `
+    SELECT id, key, label
+    FROM tags
+    WHERE key = ?`.trim(),
+    byTagFirst: `
+    SELECT n.slug, n.title, n.language
+    FROM tags AS t
+    JOIN node_tags AS nt ON nt.tag_id = t.id
+    JOIN nodes AS n ON n.id = nt.node_id
+    WHERE t.key = ?
+    ORDER BY n.slug
+    LIMIT ?`.trim(),
+    byTagAfter: `
+    SELECT n.slug, n.title, n.language
+    FROM tags AS t
+    JOIN node_tags AS nt ON nt.tag_id = t.id
+    JOIN nodes AS n ON n.id = nt.node_id
+    WHERE t.key = ? AND n.slug > ?
+    ORDER BY n.slug
+    LIMIT ?`.trim(),
+    /**
+     * One-hop neighbours, incoming and outgoing unioned once. The union is over
+     * ids, so a reciprocal pair appears once and the center is never a neighbour.
+     */
+    neighbors: `
+    WITH neighbors(id) AS (
+        SELECT target_id FROM edges WHERE source_id = ?
+        UNION
+        SELECT source_id FROM edges WHERE target_id = ?
+    )
+    SELECT n.id, n.slug, n.title, n.language
+    FROM neighbors AS x
+    JOIN nodes AS n ON n.id = x.id
+    ORDER BY n.slug`.trim(),
+    nodeBySlug: `
+    SELECT id, slug, title, language
+    FROM nodes
+    WHERE slug = ?`.trim(),
+    allNodes: `
+    SELECT id, slug, title, language
+    FROM nodes
+    ORDER BY slug`.trim(),
+    allEdges: `
+    SELECT source_id, target_id
+    FROM edges
+    ORDER BY source_id, target_id`.trim(),
+    /**
+     * Every tagged note, with its tag's canonical key and label.
+     *
+     * The build reads this once and groups in memory, which is the access path
+     * `docs/core-design/sqlite-contract.md` names for "build-time tags for all
+     * notes": `node_tags` is scanned through its primary key and the two joins
+     * probe `tags` and `nodes` by primary key, so the cost is the membership
+     * count and never an N-per-page scan. `slug` before `key` is the grouping
+     * order the reader wants; the `ORDER BY` is explicit rather than left to the
+     * tables' storage order, so two readers see the rows in one order.
+     */
+    allNodeTags: `
+    SELECT n.slug, t.key, t.label
+    FROM node_tags AS nt
+    JOIN tags AS t ON t.id = nt.tag_id
+    JOIN nodes AS n ON n.id = nt.node_id
+    ORDER BY n.slug, t.key`.trim(),
+    /** Distinct adjacent notes per node, as one aggregate over the edge set. */
+    nodeDegrees: `
+    SELECT node_id AS id, COUNT(DISTINCT neighbour) AS degree FROM (
+      SELECT source_id AS node_id, target_id AS neighbour FROM edges
+      UNION
+      SELECT target_id AS node_id, source_id AS neighbour FROM edges
+    )
+    GROUP BY node_id`.trim(),
+    /** A tag's member nodes. The tag key is the only parameter. */
+    tagNodes: `
+    SELECT n.id, n.slug, n.title, n.language
+    FROM tags AS t
+    JOIN node_tags AS nt ON nt.tag_id = t.id
+    JOIN nodes AS n ON n.id = nt.node_id
+    WHERE t.key = ?
+    ORDER BY n.slug`.trim(),
+    /**
+     * Distinct adjacent notes per node **within one tag's subgraph**, mirroring
+     * `nodeDegrees` scoped to a tag: both endpoints must be members, and the
+     * `UNION` plus `COUNT(DISTINCT neighbour)` make a reciprocal pair one
+     * neighbour, as `selectGlobal` computes it. Each branch is driven by the
+     * tag's memberships: the first searches out-edges through the edge primary
+     * key, the second searches in-edges through `edges_by_target`, and both probe
+     * the other endpoint's membership by primary key. Cost follows the members'
+     * edges rather than a member-by-member `IN (members)` list, which makes
+     * SQLite probe the member cross-product and degrades with tag size. A member
+     * with no in-tag edge has no row; callers treat a missing id as degree 0,
+     * which is also how `nodeDegrees` covers an isolated node.
+     */
+    tagNodeDegrees: `
+    WITH members(id) AS (
+      SELECT nt.node_id
+      FROM tags AS t
+      JOIN node_tags AS nt ON nt.tag_id = t.id
+      WHERE t.key = ?
+    )
+    SELECT node_id AS id, COUNT(DISTINCT neighbour) AS degree FROM (
+      SELECT e.source_id AS node_id, e.target_id AS neighbour
+      FROM edges AS e
+      JOIN members AS s ON s.id = e.source_id
+      JOIN members AS g ON g.id = e.target_id
+      UNION
+      SELECT e.target_id AS node_id, e.source_id AS neighbour
+      FROM edges AS e
+      JOIN members AS g ON g.id = e.target_id
+      JOIN members AS s ON s.id = e.source_id
+    )
+    GROUP BY node_id`.trim(),
+};
+/**
+ * Turn up to `pageSize + 1` ordered rows into one page.
+ *
+ * `nextCursor` is the last **returned** slug, never the lookahead row's; a
+ * cursor built from the extra row skips a real result on the next request.
+ */
+export function pageOf(rows, pageSize) {
+    const items = rows.slice(0, pageSize);
+    const nextCursor = rows.length > pageSize ? (items.at(-1)?.slug ?? null) : null;
+    return { items, nextCursor };
+}
+/**
+ * Whether a slug is a plausible lookup key before a query is attempted.
+ *
+ * Uses the shared note-slug grammar (`isNoteSlug`) rather than only a length
+ * bound: SQL binds the value as a parameter, so a traversal string cannot
+ * escape, but a request that is not a slug is a caller defect that should fail
+ * as `bad-argument` rather than silently return "no match".
+ */
+export function isLookupSlug(value) {
+    return typeof value === 'string' && value.length > 0 && isNoteSlug(value);
+}
+/** Route-key characters a canonical tag key may carry; no separators or controls. */
+const LOOKUP_TAG_INVALID = /[/\p{Cc}\p{Cf}]/u;
+/**
+ * Whether a canonical tag key is plausible before a query is attempted.
+ *
+ * Wider than a slug because a tag key may be any script (including CJK and
+ * combining marks) and may contain `_`; it must still be one path segment.
+ */
+export function isLookupTagKey(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= 128 &&
+        !LOOKUP_TAG_INVALID.test(value));
+}
+/**
+ * Bound a requested page size to the accepted range. The Worker validates this
+ * rather than trusting a caller-supplied number; LIMIT bounds output, not work.
+ */
+export const DEFAULT_PAGE_SIZE = 50;
+export const MAX_PAGE_SIZE = 200;
+export function normalizePageSize(value) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0)
+        return DEFAULT_PAGE_SIZE;
+    return Math.min(value, MAX_PAGE_SIZE);
+}