@inharness-ai/claude4spec 1.0.0

package/dist/server/services/page-serializer.js

@@ -0,0 +1,359 @@
+/**
+ * PageSerializer — M02 stays out of L9 plugin host (M17 decyzja 1).
+ * Lives outside `EntitySerializer` registry; provides parallel
+ * snapshot/restore/diff for markdown pages.
+ *
+ * Snapshot shape — `PageSnapshotData` per `db-m17-snapshots.md` (`dbm17shp01`).
+ * Diff variant C (M17 decyzja 10): section-level operations + mandatory
+ * `line_diff` inside each `section_modified` + `frontmatter_diff` /
+ * `xml_refs_diff` side-channels.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { diffLines } from 'diff';
+import { ANCHOR_PATTERN_SOURCE } from '../../shared/anchor-pattern.js';
+import { parseXmlTags } from '../../shared/xml-tags.js';
+export const PAGE_SERIALIZER_VERSION = '1.1.0';
+const ANCHOR_RE = new RegExp(ANCHOR_PATTERN_SOURCE, 'g');
+const ANCHOR_LINE_RE = new RegExp(`^\\s*${ANCHOR_PATTERN_SOURCE}\\s*$`);
+const ANCHOR_INLINE_RE = new RegExp(ANCHOR_PATTERN_SOURCE);
+const CODE_FENCE_RE = /^\s*```/m;
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*$/;
+/**
+ * Compute line-level diff between two strings using Myers algorithm
+ * (via `diff` npm). Returns a flat list of keep/added/removed lines
+ * preserving order. Trailing newlines are normalized so identical
+ * content with/without final \n compares equal.
+ */
+export function computeLineDiff(a, b) {
+    const lines = [];
+    const parts = diffLines(a, b);
+    for (const part of parts) {
+        const op = part.added ? 'added' : part.removed ? 'removed' : 'keep';
+        const partLines = part.value.split('\n');
+        // diffLines emits trailing empty string for blocks that end in \n; drop it.
+        if (partLines.length > 0 && partLines[partLines.length - 1] === '')
+            partLines.pop();
+        for (const content of partLines) {
+            lines.push({ op, content });
+        }
+    }
+    // Inside fenced code blocks (```), whitespace and HTML comments can be
+    // semantically meaningful (YAML, Python, indent-DSL, markdown-in-markdown).
+    // Skip noise filtering entirely when either side contains a code fence.
+    if (CODE_FENCE_RE.test(a) || CODE_FENCE_RE.test(b)) {
+        return { lines };
+    }
+    const filtered = lines.filter((l) => {
+        if (l.op === 'keep')
+            return true;
+        if (l.content.trim() === '')
+            return false;
+        if (ANCHOR_LINE_RE.test(l.content))
+            return false;
+        return true;
+    });
+    return { lines: filtered };
+}
+/** Extract anchors in document order. */
+export function extractAnchorsInOrder(content) {
+    const out = [];
+    ANCHOR_RE.lastIndex = 0;
+    let m;
+    while ((m = ANCHOR_RE.exec(content)) !== null) {
+        if (m[1])
+            out.push(m[1]);
+    }
+    return out;
+}
+export class PageSerializer {
+    pages;
+    version = PAGE_SERIALIZER_VERSION;
+    constructor(pages) {
+        this.pages = pages;
+    }
+    /**
+     * Read the file from disk and produce a deterministic, byte-faithful
+     * snapshot. Reads `content` byte-for-byte (preserves BOM, line endings).
+     */
+    async snapshot(relPath) {
+        const abs = path.join(this.pages.root, relPath);
+        const raw = await fs.readFile(abs, 'utf-8');
+        return this.snapshotFromContent(relPath, raw);
+    }
+    /** Build snapshot from already-read content (used for delete tombstones). */
+    snapshotFromContent(relPath, content) {
+        const parsed = matter(content);
+        const anchors = extractAnchorsInOrder(content);
+        const xml_refs = parseXmlTags(content).map((t) => ({
+            tagType: t.kind,
+            attributes: t.attrs,
+            position: t.start,
+        }));
+        return {
+            path: relPath,
+            content,
+            frontmatter: (parsed.data ?? {}),
+            anchors,
+            xml_refs,
+        };
+    }
+    /**
+     * Section-level diff (variant C in M17 decyzja 10). Sections keyed by
+     * 8-char anchor (`<!-- anchor: ... -->`). Reorder without content change
+     * → moved_section. Heading edited → counted as modified (heading is part
+     * of section content in our parser). Each `modified` section carries a
+     * mandatory `line_diff` computed via Myers diff over section bodies.
+     */
+    diff(a, b, relPath) {
+        const empty = {
+            added_sections: [],
+            removed_sections: [],
+            modified_sections: [],
+            moved_sections: [],
+        };
+        if (a == null && b == null) {
+            return { path: relPath, op: 'noop', ...empty, frontmatter_diff: null, xml_refs_diff: null };
+        }
+        if (a == null) {
+            const sections = parseSections(b.content);
+            return {
+                path: relPath,
+                op: 'created',
+                added_sections: sections,
+                removed_sections: [],
+                modified_sections: [],
+                moved_sections: [],
+                frontmatter_diff: frontmatterDiff({}, b.frontmatter),
+                xml_refs_diff: { added: b.xml_refs, removed: [] },
+            };
+        }
+        if (b == null) {
+            const sections = parseSections(a.content);
+            return {
+                path: relPath,
+                op: 'deleted',
+                added_sections: [],
+                removed_sections: sections,
+                modified_sections: [],
+                moved_sections: [],
+                frontmatter_diff: frontmatterDiff(a.frontmatter, {}),
+                xml_refs_diff: { added: [], removed: a.xml_refs },
+            };
+        }
+        const aSec = parseSections(a.content);
+        const bSec = parseSections(b.content);
+        const aMap = new Map(aSec.map((s) => [s.anchor, s]));
+        const bMap = new Map(bSec.map((s) => [s.anchor, s]));
+        const added = [];
+        const removed = [];
+        const modified = [];
+        const moved = [];
+        for (const [anchor, sec] of bMap) {
+            if (!aMap.has(anchor))
+                added.push(sec);
+        }
+        for (const [anchor, sec] of aMap) {
+            const other = bMap.get(anchor);
+            if (!other) {
+                removed.push(sec);
+                continue;
+            }
+            if (sec.content === other.content && sec.heading === other.heading) {
+                if (sec.position !== other.position) {
+                    moved.push({ anchor, from_position: sec.position, to_position: other.position });
+                }
+                continue;
+            }
+            const lineDiff = computeLineDiff(sec.content, other.content);
+            const hasContentChange = lineDiff.lines.some((l) => l.op !== 'keep');
+            const headingChanged = sec.heading !== other.heading;
+            if (hasContentChange || headingChanged) {
+                modified.push({
+                    anchor,
+                    heading: other.heading,
+                    level: other.level,
+                    line_diff: lineDiff,
+                });
+            }
+            else if (sec.position !== other.position) {
+                moved.push({ anchor, from_position: sec.position, to_position: other.position });
+            }
+        }
+        const fmDiff = frontmatterDiff(a.frontmatter, b.frontmatter);
+        const xmlDiff = xmlRefsDiff(a.xml_refs, b.xml_refs);
+        const anyChange = added.length || removed.length || modified.length || moved.length || fmDiff || xmlDiff;
+        return {
+            path: relPath,
+            op: anyChange ? 'modified' : 'noop',
+            added_sections: added,
+            removed_sections: removed,
+            modified_sections: modified,
+            moved_sections: moved,
+            frontmatter_diff: fmDiff,
+            xml_refs_diff: xmlDiff,
+        };
+    }
+}
+/**
+ * Split markdown content into sections keyed by 8-char anchor. A section spans
+ * from a heading (with anchor comment) to the next heading of equal or higher
+ * level. Content without an anchor is grouped under an implicit root section
+ * keyed by `__root__`.
+ */
+export function parseSections(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let position = 0;
+    let currentAnchor = null;
+    let currentHeading = '';
+    let currentLevel = 0;
+    let currentLines = [];
+    const flush = () => {
+        if (currentAnchor) {
+            sections.push({
+                anchor: currentAnchor,
+                heading: currentHeading,
+                level: currentLevel,
+                content: currentLines.join('\n'),
+                position: position++,
+            });
+        }
+        else if (currentLines.length > 0 && currentLines.some((l) => l.trim().length > 0)) {
+            sections.push({
+                anchor: '__root__',
+                heading: '',
+                level: 0,
+                content: currentLines.join('\n'),
+                position: position++,
+            });
+        }
+        currentAnchor = null;
+        currentHeading = '';
+        currentLevel = 0;
+        currentLines = [];
+    };
+    let pendingAnchor = null;
+    let pendingBlanks = [];
+    // Orphan a pending anchor + its buffered blank lines into the current section
+    // (i.e. anchor never met a heading — fall back to treating it as inline content).
+    const orphanPending = () => {
+        if (pendingAnchor !== null) {
+            currentLines.push(`<!-- anchor: ${pendingAnchor} -->`);
+            pendingAnchor = null;
+        }
+        if (pendingBlanks.length > 0) {
+            currentLines.push(...pendingBlanks);
+            pendingBlanks = [];
+        }
+    };
+    for (const line of lines) {
+        const anchorMatch = line.match(ANCHOR_INLINE_RE);
+        if (anchorMatch && anchorMatch[1]) {
+            // A second anchor before any heading appeared — orphan the previous one
+            // (matches historical behavior for the rare `anchor\nanchor\nheading` case)
+            // before adopting the new pending anchor.
+            orphanPending();
+            pendingAnchor = anchorMatch[1];
+            continue;
+        }
+        // Blank line between anchor and heading: buffer it, keep the anchor pending.
+        // Canonical indexer layout is `anchor\n\nheading`, so this is the common case.
+        if (pendingAnchor !== null && line.trim() === '') {
+            pendingBlanks.push(line);
+            continue;
+        }
+        const headingMatch = line.match(HEADING_RE);
+        if (headingMatch && pendingAnchor !== null) {
+            flush();
+            currentAnchor = pendingAnchor;
+            currentLevel = headingMatch[1].length;
+            currentHeading = headingMatch[2].trim();
+            // Buffered blanks (if any) become leading whitespace of the new section,
+            // so concatenating section contents reconstructs the on-disk body modulo
+            // the consumed anchor line itself.
+            currentLines = pendingBlanks.length > 0 ? [...pendingBlanks, line] : [line];
+            pendingAnchor = null;
+            pendingBlanks = [];
+            continue;
+        }
+        // Non-blank, non-heading, non-anchor line: anchor (if any) never found its
+        // heading — orphan it together with any buffered blanks, then push current line.
+        orphanPending();
+        currentLines.push(line);
+    }
+    // File ended with a dangling anchor (and maybe blanks) — orphan into trailing content.
+    orphanPending();
+    flush();
+    return sections;
+}
+function frontmatterDiff(a, b) {
+    const added = {};
+    const removed = {};
+    const changed = [];
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+        const inA = key in a;
+        const inB = key in b;
+        if (!inA && inB)
+            added[key] = b[key];
+        else if (inA && !inB)
+            removed[key] = a[key];
+        else if (JSON.stringify(a[key]) !== JSON.stringify(b[key])) {
+            changed.push({ key, from: a[key], to: b[key] });
+        }
+    }
+    if (Object.keys(added).length === 0 && Object.keys(removed).length === 0 && changed.length === 0) {
+        return null;
+    }
+    return { added, removed, changed };
+}
+function xmlRefsDiff(a, b) {
+    // Identity = (tagType, canonical attrs). Position is EXCLUDED on purpose:
+    // inserting text above a tag shifts its byte offset, which would otherwise
+    // surface as a fake `removed @ oldPos + added @ newPos` pair for a tag that
+    // didn't actually change. Identical-attribute occurrences are deduped by
+    // multiset count (not by Set membership), so duplicates are tracked correctly:
+    // 2 occurrences before, 1 after → exactly 1 reported as removed.
+    const keyOf = (r) => `${r.tagType}|${JSON.stringify(canonicalAttrs(r.attributes))}`;
+    const groupBy = (refs) => {
+        const m = new Map();
+        for (const r of refs) {
+            const k = keyOf(r);
+            const bucket = m.get(k);
+            if (bucket)
+                bucket.push(r);
+            else
+                m.set(k, [r]);
+        }
+        return m;
+    };
+    const aByKey = groupBy(a);
+    const bByKey = groupBy(b);
+    const added = [];
+    const removed = [];
+    const allKeys = new Set([...aByKey.keys(), ...bByKey.keys()]);
+    for (const k of allKeys) {
+        const aArr = aByKey.get(k) ?? [];
+        const bArr = bByKey.get(k) ?? [];
+        if (bArr.length > aArr.length) {
+            added.push(...bArr.slice(aArr.length));
+        }
+        else if (aArr.length > bArr.length) {
+            removed.push(...aArr.slice(bArr.length));
+        }
+        // Equal counts: same identity present in both → no event emitted, regardless
+        // of position changes. Pure positional shifts are not changes.
+    }
+    if (added.length === 0 && removed.length === 0)
+        return null;
+    return { added, removed };
+}
+function canonicalAttrs(attrs) {
+    const out = {};
+    for (const key of Object.keys(attrs).sort())
+        out[key] = attrs[key];
+    return out;
+}
+//# sourceMappingURL=page-serializer.js.map

package/dist/server/services/page-serializer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-serializer.js","sourceRoot":"","sources":["../../../src/server/services/page-serializer.ts"],"names":[],"mappings":"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"}

package/dist/server/services/page-version.d.ts

@@ -0,0 +1,75 @@
+/**
+ * PageVersionService — append-only versioning of markdown pages (M17 Phase 4).
+ * Parallel to VersionService but for filesystem pages. Each capture produces
+ * one row in `page_version` with `release_id = NULL` (assigned by
+ * `releaseService.createRelease`).
+ */
+import type Database from 'better-sqlite3';
+import { PageSerializer, type PageSnapshotData } from './page-serializer.js';
+export type PageChangedBy = 'user' | 'agent' | 'filesystem';
+export type PageOp = 'create' | 'update' | 'delete';
+/**
+ * Dyskryminator źródła w `page_version`. `'page'` = pagesDir (M02), `'brief'` =
+ * briefsDir (M21). Filtruje briefy z release snapshot/diff/restore — brief jest
+ * artefaktem POST-release, nie częścią release'u (M17 spec, sekcja m17top001).
+ */
+export type PageKind = 'page' | 'brief';
+export interface PageVersionListItem {
+    id: number;
+    path: string;
+    version: number;
+    op: PageOp;
+    changedBy: PageChangedBy;
+    releaseId: number | null;
+    serializerVersion: string;
+    createdAt: string;
+    /** Human-readable opis zmiany. Null = brak (filesystem watcher, legacy). */
+    changeSummary: string | null;
+}
+export interface PageVersionDetail extends PageVersionListItem {
+    data: PageSnapshotData;
+}
+export declare class PageVersionService {
+    private db;
+    private serializer;
+    constructor(db: Database.Database, serializer: PageSerializer);
+    /**
+     * Capture a new version of a page. For `op = 'delete'`, the caller must
+     * provide the last-known content (since the file is gone) — used to build
+     * a tombstone snapshot.
+     *
+     * M21 (m02multidir): caller can pass an alternative `serializer` so this
+     * single shared `PageVersionService` can capture both `pagesDir` and
+     * `briefsDir` files. Each `PageSerializer` is bound to a specific
+     * `PagesService` (= rootDir) at construction time; the path-keyed
+     * `page_version` table itself is rootDir-agnostic.
+     */
+    recordVersion(relPath: string, op: PageOp, changedBy: PageChangedBy, fallbackContent?: string, serializer?: PageSerializer, kind?: PageKind, changeSummary?: string | null): Promise<PageVersionListItem>;
+    listVersions(relPath: string): PageVersionListItem[];
+    getVersion(relPath: string, version: number): PageVersionDetail | null;
+    /**
+     * M17: latest captured version of a page at-or-before a given release.
+     * Mirrors VersionService.getLatestVersionForEntity.
+     */
+    getLatestForPath(relPath: string, releaseId?: number | null): PageVersionDetail | null;
+    /** True when this path has any captured version. Used by initial-sync hook. */
+    hasAny(relPath: string): boolean;
+    /** Distinct paths captured at-or-before a given release (or all if undefined). */
+    listPathsForRelease(releaseId: number): string[];
+    /**
+     * Count page captures with `release_id IS NULL` (waiting to be picked up by
+     * next release). Excludes briefs — briefs nigdy nie wpadają do release'u
+     * (M21 spec, sekcja m21db0001).
+     */
+    countUnreleased(): number;
+    /**
+     * Atomic: assign all unreleased page_version rows (kind='page') to a release.
+     * Returns the count of rows updated. Briefy (kind='brief') NIGDY nie wpadają
+     * do release'u — mają własną oś czasu, niezależną od release timeline.
+     */
+    assignToRelease(releaseId: number): number;
+    private nextVersionNumber;
+    private synthesizeDeleteFromLastVersion;
+    private toListItem;
+    private toDetail;
+}

package/dist/server/services/page-version.js

@@ -0,0 +1,159 @@
+/**
+ * PageVersionService — append-only versioning of markdown pages (M17 Phase 4).
+ * Parallel to VersionService but for filesystem pages. Each capture produces
+ * one row in `page_version` with `release_id = NULL` (assigned by
+ * `releaseService.createRelease`).
+ */
+export class PageVersionService {
+    db;
+    serializer;
+    constructor(db, serializer) {
+        this.db = db;
+        this.serializer = serializer;
+    }
+    /**
+     * Capture a new version of a page. For `op = 'delete'`, the caller must
+     * provide the last-known content (since the file is gone) — used to build
+     * a tombstone snapshot.
+     *
+     * M21 (m02multidir): caller can pass an alternative `serializer` so this
+     * single shared `PageVersionService` can capture both `pagesDir` and
+     * `briefsDir` files. Each `PageSerializer` is bound to a specific
+     * `PagesService` (= rootDir) at construction time; the path-keyed
+     * `page_version` table itself is rootDir-agnostic.
+     */
+    async recordVersion(relPath, op, changedBy, fallbackContent, serializer, kind = 'page', changeSummary) {
+        const ser = serializer ?? this.serializer;
+        const data = op === 'delete' && fallbackContent !== undefined
+            ? ser.snapshotFromContent(relPath, fallbackContent)
+            : op === 'delete'
+                ? this.synthesizeDeleteFromLastVersion(relPath)
+                : await ser.snapshot(relPath);
+        const next = this.nextVersionNumber(relPath);
+        const summary = typeof changeSummary === 'string' && changeSummary.length > 0
+            ? changeSummary
+            : null;
+        const info = this.db
+            .prepare(`INSERT INTO page_version (path, version, data, serializer_version, op, changed_by, kind, change_summary)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(relPath, next, JSON.stringify(data), ser.version, op, changedBy, kind, summary);
+        const row = this.db
+            .prepare(`SELECT * FROM page_version WHERE id = ?`)
+            .get(info.lastInsertRowid);
+        return this.toListItem(row);
+    }
+    listVersions(relPath) {
+        const rows = this.db
+            .prepare(`SELECT * FROM page_version WHERE path = ? ORDER BY version DESC`)
+            .all(relPath);
+        return rows.map((r) => this.toListItem(r));
+    }
+    getVersion(relPath, version) {
+        const row = this.db
+            .prepare(`SELECT * FROM page_version WHERE path = ? AND version = ?`)
+            .get(relPath, version);
+        return row ? this.toDetail(row) : null;
+    }
+    /**
+     * M17: latest captured version of a page at-or-before a given release.
+     * Mirrors VersionService.getLatestVersionForEntity.
+     */
+    getLatestForPath(relPath, releaseId) {
+        let row;
+        if (releaseId === undefined) {
+            row = this.db
+                .prepare(`SELECT * FROM page_version WHERE path = ?
+            ORDER BY version DESC LIMIT 1`)
+                .get(relPath);
+        }
+        else if (releaseId === null) {
+            row = this.db
+                .prepare(`SELECT * FROM page_version WHERE path = ? AND release_id IS NULL
+            ORDER BY version DESC LIMIT 1`)
+                .get(relPath);
+        }
+        else {
+            row = this.db
+                .prepare(`SELECT * FROM page_version
+            WHERE path = ? AND release_id IS NOT NULL AND release_id <= ?
+            ORDER BY version DESC LIMIT 1`)
+                .get(relPath, releaseId);
+        }
+        return row ? this.toDetail(row) : null;
+    }
+    /** True when this path has any captured version. Used by initial-sync hook. */
+    hasAny(relPath) {
+        const row = this.db
+            .prepare(`SELECT 1 FROM page_version WHERE path = ? LIMIT 1`)
+            .get(relPath);
+        return !!row;
+    }
+    /** Distinct paths captured at-or-before a given release (or all if undefined). */
+    listPathsForRelease(releaseId) {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT path FROM page_version WHERE release_id = ? ORDER BY path`)
+            .all(releaseId);
+        return rows.map((r) => r.path);
+    }
+    /**
+     * Count page captures with `release_id IS NULL` (waiting to be picked up by
+     * next release). Excludes briefs — briefs nigdy nie wpadają do release'u
+     * (M21 spec, sekcja m21db0001).
+     */
+    countUnreleased() {
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM page_version WHERE release_id IS NULL AND kind = 'page'`)
+            .get();
+        return row.n;
+    }
+    /**
+     * Atomic: assign all unreleased page_version rows (kind='page') to a release.
+     * Returns the count of rows updated. Briefy (kind='brief') NIGDY nie wpadają
+     * do release'u — mają własną oś czasu, niezależną od release timeline.
+     */
+    assignToRelease(releaseId) {
+        const info = this.db
+            .prepare(`UPDATE page_version SET release_id = ? WHERE release_id IS NULL AND kind = 'page'`)
+            .run(releaseId);
+        return Number(info.changes);
+    }
+    nextVersionNumber(relPath) {
+        const row = this.db
+            .prepare(`SELECT MAX(version) AS v FROM page_version WHERE path = ?`)
+            .get(relPath);
+        return (row.v ?? 0) + 1;
+    }
+    synthesizeDeleteFromLastVersion(relPath) {
+        const last = this.getLatestForPath(relPath);
+        if (last)
+            return last.data;
+        // No prior version — we don't have content. Tombstone with empty content.
+        return {
+            path: relPath,
+            content: '',
+            frontmatter: {},
+            anchors: [],
+            xml_refs: [],
+        };
+    }
+    toListItem(row) {
+        return {
+            id: row.id,
+            path: row.path,
+            version: row.version,
+            op: row.op,
+            changedBy: row.changed_by,
+            releaseId: row.release_id,
+            serializerVersion: row.serializer_version,
+            createdAt: row.created_at,
+            changeSummary: row.change_summary,
+        };
+    }
+    toDetail(row) {
+        return {
+            ...this.toListItem(row),
+            data: JSON.parse(row.data),
+        };
+    }
+}
+//# sourceMappingURL=page-version.js.map

package/dist/server/services/page-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-version.js","sourceRoot":"","sources":["../../../src/server/services/page-version.ts"],"names":[],"mappings":"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"}

package/dist/server/services/pages-frontmatter-indexer.d.ts

@@ -0,0 +1,51 @@
+/**
+ * M21 / M02 (m02fmidx): in-memory index of YAML frontmatter for every markdown
+ * file under both `pagesDir` and `briefsDir`. Fed by both `PagesWatcher`
+ * instances. Provides synchronous lookups for:
+ *   - hidden-tree filter (`pagesRouter` excludes pages with `frontmatter.type === 'brief'`)
+ *   - `briefService.listBriefs()` (find by `frontmatter.type === 'brief'`)
+ *   - any future module that wants to discover pages by frontmatter type
+ *
+ * Pattern derived from `TodosIndexerService` / `PagesLinkIndexerService`:
+ * debounced reindex per file, in-memory `Map<path, Record>`, WS broadcast.
+ */
+import type { PagesService } from './pages.js';
+import type { WsGateway } from '../ws/gateway.js';
+import type { PagesRootDir } from '../../shared/types.js';
+export interface FrontmatterRecord {
+    rootDir: PagesRootDir;
+    frontmatter: Record<string, unknown>;
+}
+export interface FrontmatterFindOptions {
+    rootDir?: PagesRootDir;
+}
+export declare class PagesFrontmatterIndexer {
+    private pages;
+    private briefs;
+    private ws;
+    private debounceMs;
+    private pending;
+    /** Composite key `${rootDir}:${path}` so the same path could theoretically
+     * exist in both roots without collision (defensive — collision would be a
+     * config-misconfiguration, but indexer must remain correct). */
+    private byKey;
+    constructor(pages: PagesService, briefs: PagesService, ws: WsGateway);
+    private rootFor;
+    private key;
+    schedulePage(rootDir: PagesRootDir, relPath: string): void;
+    handleUnlink(rootDir: PagesRootDir, relPath: string): void;
+    indexAll(): Promise<void>;
+    indexPage(rootDir: PagesRootDir, relPath: string, opts?: {
+        silent?: boolean;
+    }): Promise<void>;
+    getFrontmatter(rootDir: PagesRootDir, relPath: string): Record<string, unknown> | null;
+    /**
+     * Find paths whose frontmatter has `type === <type>`. Optionally restrict
+     * to a single rootDir (defaults to all). Returns sorted by path.
+     */
+    findByFrontmatterType(type: string, opts?: FrontmatterFindOptions): Array<{
+        rootDir: PagesRootDir;
+        path: string;
+        frontmatter: Record<string, unknown>;
+    }>;
+}