@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/registry.js

@@ -0,0 +1,182 @@
+/** Memory projects and their bindings to host projects (`registry.rs`); stored as `markdown/registry.json`. */
+import { randomBytes } from 'node:crypto';
+import { MAX_TITLE_CHARS, REGISTRY_FORMAT_VERSION } from './constants.js';
+import { MemoryError } from './errors.js';
+export const REGISTRY_FILE = 'registry.json';
+export class MemoryRegistry {
+    projects;
+    ignoredHostProjectIds;
+    constructor(projects = [], 
+    /** Host projects whose orphan prompt the user dismissed. */
+    ignoredHostProjectIds = []) {
+        this.projects = projects;
+        this.ignoredHostProjectIds = ignoredHostProjectIds;
+    }
+    /** Parse registry file text; a format other than version 1 is refused. */
+    static parse(text, path) {
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch (error) {
+            throw MemoryError.json(path, error instanceof Error ? error.message : String(error));
+        }
+        if (!isRecord(value) || value['version'] !== REGISTRY_FORMAT_VERSION) {
+            throw new MemoryError('unsupported_format', `Memory registry \`${path}\` must declare format version ${REGISTRY_FORMAT_VERSION}.`);
+        }
+        const projects = value['projects'];
+        const ignored = value['ignoredHostProjectIds'];
+        if (!Array.isArray(projects) || !Array.isArray(ignored) || !ignored.every(item => typeof item === 'string')) {
+            throw MemoryError.json(path, 'expected `projects` and `ignoredHostProjectIds` arrays');
+        }
+        return new MemoryRegistry(projects.map(project => parseProject(project, path)), ignored);
+    }
+    /** The versioned file text, without the final newline. */
+    toJson() {
+        return JSON.stringify({
+            version: REGISTRY_FORMAT_VERSION,
+            projects: this.projects.map(project => ({
+                id: project.id,
+                name: project.name,
+                hostProjectIds: project.hostProjectIds,
+                paths: project.paths,
+                ...project.firstCommit === undefined ? {} : { firstCommit: project.firstCommit },
+                memoryEnabled: project.memoryEnabled,
+                created: project.created,
+                updated: project.updated,
+            })),
+            ignoredHostProjectIds: this.ignoredHostProjectIds,
+        }, null, 2);
+    }
+    projectForHost(hostProjectId) {
+        return this.projects.find(project => project.hostProjectIds.includes(hostProjectId));
+    }
+    project(id) {
+        return this.projects.find(project => project.id === id);
+    }
+    projectOrThrow(id) {
+        const project = this.project(id);
+        if (project === undefined)
+            throw MemoryError.invalid(`Memory project \`${id}\` does not exist.`);
+        return project;
+    }
+    /** Create a memory project bound to a host project and return its id. */
+    createForHost(hostProjectId, rootPath, firstCommit, now) {
+        this.unbindHost(hostProjectId);
+        const id = this.unusedProjectId();
+        this.projects.push({
+            id,
+            name: directoryName(rootPath),
+            hostProjectIds: [hostProjectId],
+            paths: [rootPath],
+            ...firstCommit === undefined ? {} : { firstCommit },
+            memoryEnabled: true,
+            created: now,
+            updated: now,
+        });
+        this.ignoredHostProjectIds = this.ignoredHostProjectIds.filter(ignored => ignored !== hostProjectId);
+        return id;
+    }
+    /** Create a memory project bound to no host project, such as one restored from an export package. */
+    createUnbound(name, paths, firstCommit, now) {
+        const id = this.unusedProjectId();
+        this.projects.push({
+            id,
+            name,
+            hostProjectIds: [],
+            paths,
+            ...firstCommit === undefined ? {} : { firstCommit },
+            memoryEnabled: true,
+            created: now,
+            updated: now,
+        });
+        return id;
+    }
+    /** Bind a host project to an existing memory project and record the path. */
+    link(memoryProjectId, hostProjectId, rootPath, now) {
+        this.projectOrThrow(memoryProjectId);
+        this.unbindHost(hostProjectId);
+        const project = this.projectOrThrow(memoryProjectId);
+        project.hostProjectIds.push(hostProjectId);
+        if (!project.paths.includes(rootPath))
+            project.paths.push(rootPath);
+        project.updated = now;
+        this.ignoredHostProjectIds = this.ignoredHostProjectIds.filter(ignored => ignored !== hostProjectId);
+    }
+    ignoreHost(hostProjectId) {
+        if (!this.ignoredHostProjectIds.includes(hostProjectId))
+            this.ignoredHostProjectIds.push(hostProjectId);
+    }
+    setEnabled(memoryProjectId, enabled, now) {
+        const project = this.projectOrThrow(memoryProjectId);
+        project.memoryEnabled = enabled;
+        project.updated = now;
+    }
+    rename(memoryProjectId, name, now) {
+        const trimmed = name.trim();
+        if (trimmed === '' || [...trimmed].length > MAX_TITLE_CHARS) {
+            throw MemoryError.invalid(`A memory project name must have 1 to ${MAX_TITLE_CHARS} characters.`);
+        }
+        const project = this.projectOrThrow(memoryProjectId);
+        project.name = trimmed;
+        project.updated = now;
+    }
+    /** Orphaned projects ranked for a host project, or nothing once it is bound or dismissed. */
+    orphanCandidates(hostProjectId, rootPath, firstCommit, pathExists) {
+        if (this.projectForHost(hostProjectId) !== undefined || this.ignoredHostProjectIds.includes(hostProjectId))
+            return [];
+        const name = directoryName(rootPath).toLowerCase();
+        const score = (candidate) => candidate.reasons.reduce((sum, reason) => sum + (reason === 'same_first_commit' ? 2 : 1), 0);
+        return this.projects
+            .filter(project => project.paths.length > 0 && !project.paths.some(pathExists))
+            .map((project) => {
+            const reasons = [];
+            if (project.paths.some(path => directoryName(path).toLowerCase() === name))
+                reasons.push('same_directory_name');
+            if (firstCommit !== undefined && project.firstCommit === firstCommit)
+                reasons.push('same_first_commit');
+            return { project, reasons };
+        })
+            .sort((left, right) => score(right) - score(left) || compare(right.project.updated, left.project.updated));
+    }
+    unbindHost(hostProjectId) {
+        for (const project of this.projects)
+            project.hostProjectIds = project.hostProjectIds.filter(bound => bound !== hostProjectId);
+    }
+    unusedProjectId() {
+        for (;;) {
+            const candidate = `p-${randomHex(10)}`;
+            if (this.project(candidate) === undefined)
+                return candidate;
+        }
+    }
+}
+/** The last path component, accepting both separators. */
+export function directoryName(path) {
+    const trimmed = path.replace(/[/\\]+$/, '');
+    return trimmed.split(/[/\\]/).pop() ?? path;
+}
+/** Lowercase hex of the given length, like the prefix of a simple UUID. */
+export function randomHex(length) {
+    return randomBytes(Math.ceil(length / 2)).toString('hex').slice(0, length);
+}
+/** Ordinal string comparison, the order Rust's `str::cmp` gives. */
+export function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function parseProject(value, path) {
+    const fields = ['id', 'name', 'hostProjectIds', 'paths', 'firstCommit', 'memoryEnabled', 'created', 'updated'];
+    if (!isRecord(value) || Object.keys(value).some(key => !fields.includes(key)))
+        throw MemoryError.json(path, 'a project has unknown fields');
+    const { id, name, hostProjectIds, paths, firstCommit, memoryEnabled, created, updated } = value;
+    const strings = (items) => Array.isArray(items) && items.every(item => typeof item === 'string');
+    if (typeof id !== 'string' || typeof name !== 'string' || !strings(hostProjectIds) || !strings(paths)
+        || (firstCommit !== undefined && typeof firstCommit !== 'string') || typeof memoryEnabled !== 'boolean'
+        || typeof created !== 'string' || typeof updated !== 'string') {
+        throw MemoryError.json(path, `project ${JSON.stringify(id)} has fields of the wrong type`);
+    }
+    return { id, name, hostProjectIds, paths, ...firstCommit === undefined ? {} : { firstCommit }, memoryEnabled, created, updated };
+}
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/scope.d.ts

@@ -0,0 +1,13 @@
+/** The three memory scopes and their preset sections (`scope.rs`). */
+export type MemoryScope = 'user' | 'space' | 'project';
+/** Every scope in display order. */
+export declare const SCOPES: readonly MemoryScope[];
+/** Stable key of the base section injected in full for space and project. */
+export declare const BASE_SECTION_KEY = "base";
+export declare function isScope(value: unknown): value is MemoryScope;
+/** Conflict priority; higher wins (project > space > user). */
+export declare function scopePriority(scope: MemoryScope): number;
+/** Whether the scope separates an injected base section from a catalog. */
+export declare function hasBaseSection(scope: MemoryScope): boolean;
+/** `[key, default title]` of the sections a new file of the scope starts with. */
+export declare function presetSections(scope: MemoryScope): readonly (readonly [string, string])[];

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/scope.js

@@ -0,0 +1,24 @@
+/** The three memory scopes and their preset sections (`scope.rs`). */
+/** Every scope in display order. */
+export const SCOPES = ['user', 'space', 'project'];
+/** Stable key of the base section injected in full for space and project. */
+export const BASE_SECTION_KEY = 'base';
+export function isScope(value) {
+    return value === 'user' || value === 'space' || value === 'project';
+}
+/** Conflict priority; higher wins (project > space > user). */
+export function scopePriority(scope) {
+    return SCOPES.indexOf(scope);
+}
+/** Whether the scope separates an injected base section from a catalog. */
+export function hasBaseSection(scope) {
+    return scope !== 'user';
+}
+/** `[key, default title]` of the sections a new file of the scope starts with. */
+export function presetSections(scope) {
+    switch (scope) {
+        case 'user': return [['identity', 'Identity'], ['communication', 'Communication'], ['expertise', 'Expertise']];
+        case 'space': return [[BASE_SECTION_KEY, 'Base'], ['conventions', 'Conventions'], ['environment', 'Environment'], ['references', 'References']];
+        case 'project': return [[BASE_SECTION_KEY, 'Base'], ['architecture', 'Architecture'], ['constraints', 'Constraints'], ['pitfalls', 'Pitfalls'], ['in-progress', 'In progress']];
+    }
+}

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/search.d.ts

@@ -0,0 +1,65 @@
+/** Node search and outline (`search.rs`), modelled on `rg` → owner and `markdown-menu`. */
+import { type NodeView } from './document.js';
+import { type MemoryScope } from './scope.js';
+import { type ScopeDocuments } from './store.js';
+/** Arguments of `memory_search`. */
+export interface SearchRequest {
+    /** Patterns combined with OR. */
+    readonly patterns?: readonly string[];
+    /** Treat patterns as literal text. */
+    readonly fixedStrings?: boolean;
+    /** Case-insensitive matching; defaults to true. */
+    readonly ignoreCase?: boolean;
+    /** Scopes to search; empty means every available scope. */
+    readonly scopes?: readonly MemoryScope[];
+    /** Section key or H1 title filter. */
+    readonly section?: string;
+    /** Title path prefix filter, segments separated by `/` or `›`. */
+    readonly pathPrefix?: string;
+    /** Exact node ids to read instead of patterns. */
+    readonly ids?: readonly string[];
+    /** Nodes per page. */
+    readonly limit?: number;
+    /** Continuation cursor from a previous result. */
+    readonly cursor?: string;
+}
+/** Arguments of `memory_outline`. */
+export interface OutlineRequest {
+    readonly scopes?: readonly MemoryScope[];
+    readonly section?: string;
+    readonly pathPrefix?: string;
+    /** Deepest heading level to list, 1 to 4. */
+    readonly depth?: number;
+}
+/** One matched or requested node. */
+export interface SearchHit {
+    readonly view: NodeView;
+    /** Number of distinct patterns that matched. */
+    readonly matchedPatterns: number;
+    readonly titleHit: boolean;
+    /** Zero-based body line indexes with a match. */
+    readonly hitLines: ReadonlySet<number>;
+    /** One-based page shown. */
+    readonly page: number;
+    readonly pages: number;
+    /** Body text of the shown page with hit lines marked. */
+    readonly text: string;
+}
+/** One page of search results. */
+export interface SearchPage {
+    readonly hits: readonly SearchHit[];
+    /** Total matched nodes. */
+    readonly total: number;
+    /** Offset of the first hit on this page. */
+    readonly offset: number;
+    /** Number of patterns in the query; zero for an id read. */
+    readonly patternCount: number;
+    /** Notes about unavailable scopes. */
+    readonly notes: readonly string[];
+}
+/** Search the visible scopes and return one page of hits. */
+export declare function searchNodes(documents: ScopeDocuments, request: SearchRequest): SearchPage;
+/** Render a search page as model-facing text. */
+export declare function renderSearchPage(page: SearchPage): string;
+/** Render the heading tree of the visible scopes. */
+export declare function renderOutline(documents: ScopeDocuments, request: OutlineRequest): string;

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/search.js

@@ -0,0 +1,227 @@
+/** Node search and outline (`search.rs`), modelled on `rg` → owner and `markdown-menu`. */
+import { DEFAULT_SEARCH_LIMIT, MAX_NODE_LEVEL, MAX_SEARCH_LIMIT, MAX_SEARCH_PATTERNS, NODE_PAGE_BYTES, byteLength } from './constants.js';
+import { lines as bodyLines, viewTitle } from './document.js';
+import { MemoryError } from './errors.js';
+import { compare } from './registry.js';
+import { SCOPES, scopePriority } from './scope.js';
+import { scopeDocument } from './store.js';
+/** Marker placed before body lines that contain a match. */
+const HIT_MARKER = '>> ';
+/** Search the visible scopes and return one page of hits. */
+export function searchNodes(documents, request) {
+    const patterns = request.patterns ?? [];
+    const ids = request.ids ?? [];
+    const hasPatterns = patterns.some(pattern => pattern !== '');
+    if (hasPatterns === (ids.length > 0))
+        throw MemoryError.invalid('Give either `patterns` or `ids`, not both and not neither.');
+    if (patterns.length > MAX_SEARCH_PATTERNS)
+        throw MemoryError.invalid(`At most ${MAX_SEARCH_PATTERNS} patterns are allowed.`);
+    const limit = Math.min(Math.max(request.limit ?? DEFAULT_SEARCH_LIMIT, 1), MAX_SEARCH_LIMIT);
+    const { views: visible, notes } = visibleViews(documents, request.scopes ?? []);
+    const views = filterViews(visible, request.section, request.pathPrefix);
+    if (ids.length > 0) {
+        const pageRequest = parseCursor(request.cursor);
+        if (pageRequest > 1 && ids.length !== 1)
+            throw MemoryError.invalid('A page cursor with `ids` needs exactly one id.');
+        const hits = ids.map(id => {
+            const view = views.find(candidate => candidate.id === id);
+            if (view === undefined)
+                throw MemoryError.notFound(id);
+            return pagedHit(view, 0, false, new Set(), Math.max(pageRequest, 1));
+        });
+        return { hits, total: hits.length, offset: 0, patternCount: 0, notes };
+    }
+    const ignoreCase = request.ignoreCase ?? true;
+    const regexes = patterns.filter(pattern => pattern !== '').map(pattern => compile(pattern, request.fixedStrings ?? false, ignoreCase));
+    const matches = [];
+    for (const view of views) {
+        const title = viewTitle(view);
+        const body = bodyLines(view.body);
+        const matched = new Set();
+        const hitLines = new Set();
+        let titleHit = false;
+        regexes.forEach((regex, index) => {
+            if (regex.test(title)) {
+                matched.add(index);
+                titleHit = true;
+            }
+            body.forEach((line, lineIndex) => {
+                if (regex.test(line)) {
+                    matched.add(index);
+                    hitLines.add(lineIndex);
+                }
+            });
+        });
+        if (matched.size > 0)
+            matches.push({ count: matched.size, titleHit, hitLines, view });
+    }
+    matches.sort((left, right) => right.count - left.count
+        || Number(right.titleHit) - Number(left.titleHit)
+        || scopePriority(right.view.scope) - scopePriority(left.view.scope)
+        || compare(updated(right.view), updated(left.view)));
+    const offset = parseCursor(request.cursor) - 1;
+    const hits = matches.slice(offset, offset + limit).map(match => pagedHit(match.view, match.count, match.titleHit, match.hitLines, undefined));
+    return { hits, total: matches.length, offset, patternCount: regexes.length, notes };
+}
+/** Render a search page as model-facing text. */
+export function renderSearchPage(page) {
+    const output = [...page.notes];
+    if (page.total === 0) {
+        output.push('No memory node matched. Try other wording or synonyms, or list titles with memory_outline.');
+        return output.join('\n');
+    }
+    if (page.patternCount > 0)
+        output.push(`${page.total} node(s) matched; showing ${page.offset + 1}-${page.offset + page.hits.length}.`);
+    for (const hit of page.hits) {
+        const view = hit.view;
+        output.push('', `## [${view.scope}] ${view.path.join(' › ')}`);
+        const facts = [`id: ${view.id}`, `revision: ${view.revision}`];
+        if (view.meta !== undefined) {
+            facts.push(`updated: ${view.meta.updated.replace('T', ' ').replace(/Z+$/, '')}`, `source: ${view.meta.source}`);
+        }
+        if (page.patternCount > 0)
+            facts.push(`matched: ${hit.matchedPatterns}/${page.patternCount} patterns${hit.titleHit ? ' (title)' : ''}`);
+        output.push(facts.join(' · '));
+        if (hit.text !== '')
+            output.push(hit.text);
+        if (view.children.length > 0)
+            output.push(`children: ${view.children.join(' · ')}`);
+        if (hit.pages > 1) {
+            const next = hit.page < hit.pages ? `; continue with ids=["${view.id}"] and cursor="${hit.page + 1}"` : '';
+            output.push(`page ${hit.page}/${hit.pages}${next}`);
+        }
+    }
+    const shown = page.offset + page.hits.length;
+    if (page.patternCount > 0 && shown < page.total)
+        output.push('', `More nodes matched; continue with cursor="${shown + 1}".`);
+    return output.join('\n');
+}
+/** Render the heading tree of the visible scopes. */
+export function renderOutline(documents, request) {
+    const depth = request.depth ?? MAX_NODE_LEVEL;
+    if (!Number.isInteger(depth) || depth < 1 || depth > MAX_NODE_LEVEL)
+        throw MemoryError.invalid(`\`depth\` must be between 1 and ${MAX_NODE_LEVEL}.`);
+    const { views: visible, notes } = visibleViews(documents, request.scopes ?? []);
+    const views = filterViews(visible, request.section, request.pathPrefix);
+    const output = [...notes];
+    for (const scope of SCOPES) {
+        const scopeViews = views.filter(view => view.scope === scope);
+        if (scopeViews.length === 0)
+            continue;
+        const label = scope === 'project' && documents.project !== undefined ? `project ${documents.project.project.name}` : scope;
+        if (output.length > 0)
+            output.push('');
+        output.push(`[${label}] ${scopeViews.length} node(s)`);
+        for (const view of scopeViews.filter(candidate => candidate.level <= depth)) {
+            const facts = [view.id, `r:${view.revision}`];
+            if (view.meta !== undefined) {
+                facts.push([...view.meta.updated].slice(0, 10).join(''));
+                if (view.meta.section !== undefined)
+                    facts.push(`section:${view.meta.section}`);
+            }
+            if (view.body !== '')
+                facts.push(`${byteLength(view.body)} B`);
+            if (view.level === depth && view.descendants > 0)
+                facts.push(`+${view.descendants} below`);
+            output.push(`${'#'.repeat(view.level)} ${viewTitle(view)} (${facts.join(' · ')})`);
+        }
+    }
+    if (output.length === 0)
+        output.push('Memory is empty. Record durable facts with memory_write.');
+    return output.join('\n');
+}
+/** Views of the requested scopes, and notes for unavailable ones. */
+function visibleViews(documents, scopes) {
+    const views = [];
+    const notes = [];
+    for (const scope of scopes.length === 0 ? SCOPES : scopes) {
+        const document = scopeDocument(documents, scope);
+        if (document !== undefined)
+            views.push(...document.views(scope));
+        else if (scopes.length > 0)
+            notes.push('[project] No project memory exists yet; it is created by the first project write.');
+    }
+    return { views, notes };
+}
+/** Apply section and path-prefix filters. */
+function filterViews(views, section, pathPrefix) {
+    const wanted = section?.trim() || undefined;
+    const prefix = (pathPrefix ?? '').split(/[/›]/).map(segment => segment.trim().toLowerCase()).filter(segment => segment !== '');
+    return views
+        .filter(view => wanted === undefined || view.section === wanted || (view.path[0] !== undefined && asciiLower(view.path[0]) === asciiLower(wanted)))
+        .filter(view => prefix.length <= view.path.length && prefix.every((segment, index) => view.path[index]?.toLowerCase() === segment));
+}
+/** Rust `eq_ignore_ascii_case` compares with only ASCII letters folded. */
+function asciiLower(text) {
+    return text.replace(/[A-Z]/g, letter => letter.toLowerCase());
+}
+/**
+ * Compile one pattern. VulcanCode uses Rust's `regex` crate; JavaScript's Unicode regex accepts
+ * the same common syntax (classes, alternation, anchors, `\b`, `\d`, `\w`, `\s`).
+ */
+function compile(pattern, fixed, ignoreCase) {
+    const source = fixed ? escapeRegex(pattern) : pattern;
+    try {
+        return new RegExp(source, ignoreCase ? 'iu' : 'u');
+    }
+    catch (error) {
+        throw MemoryError.invalid(`Pattern \`${pattern}\` is not a valid regex (${error instanceof Error ? error.message : String(error)}); set fixedStrings for literal text.`);
+    }
+}
+function escapeRegex(text) {
+    return text.replace(/[\\^$.*+?()[\]{}|/]/g, '\\$&');
+}
+/** Parse a one-based cursor; absent means 1. */
+function parseCursor(cursor) {
+    const text = cursor?.trim() ?? '';
+    if (text === '')
+        return 1;
+    const value = /^\+?\d+$/.test(text) ? Number(text) : Number.NaN;
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw MemoryError.invalid(`Cursor \`${text}\` is not a page number.`);
+    return value;
+}
+/** A node's update time for ordering; nodes without metadata sort last. */
+function updated(view) {
+    return view.meta?.updated ?? '';
+}
+/** A hit showing the requested page, or the page of the first hit line. */
+function pagedHit(view, matchedPatterns, titleHit, hitLines, requestedPage) {
+    const body = bodyLines(view.body);
+    const pages = pageRanges(body);
+    const pageCount = Math.max(pages.length, 1);
+    let page;
+    if (requestedPage !== undefined) {
+        if (requestedPage > pageCount)
+            throw MemoryError.invalid(`Node \`${view.id}\` has ${pageCount} page(s).`);
+        page = requestedPage;
+    }
+    else {
+        const first = Math.min(...hitLines);
+        const index = pages.findIndex(([start, end]) => first >= start && first < end);
+        page = index < 0 ? 1 : index + 1;
+    }
+    const range = pages[page - 1];
+    const text = range === undefined
+        ? ''
+        : body.slice(range[0], range[1]).map((line, offset) => hitLines.has(range[0] + offset) ? `${HIT_MARKER}${line}` : line).join('\n');
+    return { view, matchedPatterns, titleHit, hitLines, page, pages: pageCount, text };
+}
+/** Split body lines into `[start, end)` pages of at most {@link NODE_PAGE_BYTES}, breaking only between lines. */
+function pageRanges(body) {
+    const pages = [];
+    let start = 0;
+    let bytes = 0;
+    body.forEach((line, index) => {
+        const cost = byteLength(line) + 1;
+        if (index > start && bytes + cost > NODE_PAGE_BYTES) {
+            pages.push([start, index]);
+            start = index;
+            bytes = 0;
+        }
+        bytes += cost;
+    });
+    if (start < body.length)
+        pages.push([start, body.length]);
+    return pages;
+}

package/node_modules/@openvulcan/dsh-vulcan-memory/lib/markdown/snapshot.d.ts

@@ -0,0 +1,34 @@
+/** Injection snapshot: full-text parts, catalogs and their budget usage (`snapshot.rs`). */
+import type { InjectionBudget } from '../settings.js';
+import { type MemoryDocument } from './document.js';
+import { type MemoryScope } from './scope.js';
+import type { ScopeDocuments } from './store.js';
+/** One budgeted part of the injection. */
+export type BudgetPart = 'user' | 'spaceBase' | 'projectBase' | 'spaceCatalog' | 'projectCatalog';
+/** Usage of one budget part. */
+export interface BudgetUsage {
+    readonly part: BudgetPart;
+    /** Tokens the full content needs. */
+    readonly tokens: number;
+    /** Configured budget. */
+    readonly budget: number;
+    /** Titles left out of a full-text part, or the catalog depth that was dropped. */
+    readonly omitted: readonly string[];
+}
+/** Whether content needs more than the budget. */
+export declare function overBudget(usage: BudgetUsage): boolean;
+/** Whether usage reached the warning ratio without exceeding the budget. */
+export declare function nearBudget(usage: BudgetUsage): boolean;
+/** One usage line for a write receipt. */
+export declare function renderUsageLine(usage: BudgetUsage): string;
+/** The text injected at the start of a session and after compaction, with its usage. */
+export interface InjectionSnapshot {
+    /** Model-facing snapshot text; empty when every scope is empty. */
+    readonly content: string;
+    /** Usage of every part that has content. */
+    readonly usage: readonly BudgetUsage[];
+}
+/** Usage of the full-text part of a scope, for write receipts. */
+export declare function baseUsage(scope: MemoryScope, document: MemoryDocument, budget: InjectionBudget): BudgetUsage;
+/** The injection snapshot of every visible scope. */
+export declare function buildInjectionSnapshot(documents: ScopeDocuments, budget: InjectionBudget): InjectionSnapshot;