/**
 * Bounded status projection of the published graph assessment (T12560).
 *
 * `cleo nexus status` used to emit `assessment.files` whole: one row per
 * assessed file at ~635 B each, so the envelope grew with the repository —
 * 3.9 MB on this one, and 391 MB for one reporter. The status call is the one
 * every agent is told to make FIRST, so its size must not depend on how many
 * files exist.
 *
 * The projection keeps the counts (`fileCount`, `filesByStatus`) and one page
 * of rows (`filesPage`, 20 by default). The complete list is returned under
 * `files` only when every row is explicitly requested; otherwise it is named
 * in `_withheld` with its UTF-8 JSON size, following the MVI projection rule
 * that a partial copy is never placed under the real field name.
 *
 * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
 *
 * @task T12560
 * @module nexus/assessment-projection
 */
import type { GraphIndexAssessment, GraphIndexAssessmentProjection, GraphIndexFileStatus, GraphIndexReferenceKind, GraphIndexReferenceKindCounts, GraphIndexReferencePage, GraphIndexReferenceReport } from '@cleocode/contracts';
/** Rows in the default page of `assessment.filesPage`. */
export declare const DEFAULT_ASSESSMENT_FILE_PAGE_SIZE = 20;
/** Every file processing outcome, in report order. */
export declare const GRAPH_INDEX_FILE_STATUSES: readonly GraphIndexFileStatus[];
/** Which file rows a status projection returns. */
export interface AssessmentFilesRequest {
    /** Return every row under `files`; paging options narrow it back to a page. */
    all?: boolean;
    /** Page size; `0` requests every remaining row. Defaults to {@link DEFAULT_ASSESSMENT_FILE_PAGE_SIZE}. */
    limit?: number;
    /** Rows to skip before the page. Defaults to 0. */
    offset?: number;
    /** Page only rows with this status. */
    status?: GraphIndexFileStatus;
}
/** Raw CLI flag values accepted by {@link parseAssessmentFilesRequest}. */
export interface AssessmentFilesFlags {
    /** `--files`. */
    files?: boolean;
    /** `--limit`. */
    limit?: string;
    /** `--offset`. */
    offset?: string;
    /** `--file-status`. */
    fileStatus?: string;
}
/**
 * Validate `cleo nexus status` file-paging flags.
 * @param flags - Raw flag values as the CLI received them.
 * @returns The validated request.
 * @throws CleoError with `INVALID_INPUT` for a malformed count or unknown status.
 * @example
 * ```ts
 * parseAssessmentFilesRequest({ limit: '50', offset: '100', fileStatus: 'failed' });
 * ```
 */
export declare function parseAssessmentFilesRequest(flags: AssessmentFilesFlags): AssessmentFilesRequest;
/**
 * Project an assessment for `cleo nexus status`: counts plus one page of file rows.
 *
 * `files` is returned whole only for `{ all: true }` (or `limit: 0`) with no
 * offset or status filter. Every other request returns `filesPage` and names
 * `files` in `_withheld` with the full list's UTF-8 JSON size, so a consumer
 * never mistakes a page for the complete list.
 * @param assessment - The published assessment summary.
 * @param request - Which rows to return; the default is the first 20.
 * @returns The bounded projection.
 * @example
 * ```ts
 * const status = projectAssessmentFiles(assessment);
 * status.filesByStatus.failed; // gaps, without loading the list into the envelope
 * ```
 */
export declare function projectAssessmentFiles(assessment: GraphIndexAssessment, request?: AssessmentFilesRequest): GraphIndexAssessmentProjection;
/** References in the default page of `assessment.referencesPage` (T13330). */
export declare const DEFAULT_REFERENCE_PAGE_SIZE = 20;
/**
 * Largest reference page one status call returns (T13330).
 *
 * A reference is ~700 B of JSON, so this bounds a page near 3.5 MB however
 * large the repository; the whole list is walked with `nextOffset`.
 */
export declare const MAX_REFERENCE_PAGE_SIZE = 5000;
/** Every reference limitation kind, derived from the contract's kind counts. */
export declare const GRAPH_INDEX_REFERENCE_KINDS: readonly GraphIndexReferenceKind[];
/** Which references a status projection returns (T13330). */
export interface ReferencePageRequest {
    /** Page size, 1 to {@link MAX_REFERENCE_PAGE_SIZE}. */
    limit: number;
    /** References to skip before the page. */
    offset: number;
    /** Page only references of this kind. */
    kind?: GraphIndexReferenceKind;
}
/** Raw CLI flag values accepted by {@link parseReferencePageRequest}. */
export interface ReferencePageFlags {
    /** `--references-limit`. */
    limit?: string;
    /** `--references-offset`. */
    offset?: string;
    /** `--reference-kind`. */
    kind?: string;
}
/** A page of references read from the published generation, with whole-list totals. */
export interface ReferencePageResult {
    /** References per kind across the whole list. */
    byKind: GraphIndexReferenceKindCounts;
    /** The requested page. */
    page: GraphIndexReferencePage;
    /** UTF-8 size of the whole list as one JSON array. */
    bytes: number;
}
/**
 * Validate `cleo nexus status --references` paging flags (T13330).
 * @param flags - Raw flag values as the CLI received them.
 * @returns The validated request; a 20-reference first page by default.
 * @throws CleoError with `INVALID_INPUT` for a malformed or out-of-range count or an unknown kind.
 * @example
 * ```ts
 * parseReferencePageRequest({ limit: '500', offset: '1000', kind: 'unresolved' });
 * ```
 */
export declare function parseReferencePageRequest(flags: ReferencePageFlags): ReferencePageRequest;
/**
 * Attach a reference page to a status projection (T13330).
 *
 * `references` is never placed in the projection: it is named in `_withheld`
 * with the whole list's UTF-8 JSON size, beside the per-kind counts and the
 * requested page, so a consumer never mistakes a page for the complete list.
 * @param projection - The bounded status projection.
 * @param result - The page and totals read from the published generation.
 * @returns The projection with `referencesByKind` and `referencesPage`.
 * @example
 * ```ts
 * const status = withReferencePage(projectAssessmentFiles(summary), page);
 * ```
 */
export declare function withReferencePage(projection: GraphIndexAssessmentProjection, result: ReferencePageResult): GraphIndexAssessmentProjection;
/** How {@link pageReferences} reads one stored reference. */
export interface ReferenceReaders {
    /** The reference's kind, validated; called for every reference. */
    kind: (item: unknown) => GraphIndexReferenceKind;
    /** The fully validated reference; called only for rows in the page. */
    row: (item: unknown) => GraphIndexReferenceReport;
}
/**
 * Fold a stream of stored references into one page plus whole-list totals (T13330).
 *
 * Every reference is counted by kind and then dropped; only the rows of the
 * requested page are kept. Memory is therefore bounded by the page whatever
 * the length of the list — 846 151 references on one repository.
 * @param items - Stored references in stored order, with their JSON sizes.
 * @param request - Page size, offset and optional kind filter.
 * @param readers - Validation for a reference's kind and for a page row.
 * @returns The page, per-kind counts, whole-list JSON size and reference count.
 * @example
 * ```ts
 * const result = await pageReferences(streamStoredReferences(blob), request, readers);
 * ```
 */
export declare function pageReferences(items: AsyncIterable<{
    item: unknown;
    bytes: number;
}> | Iterable<{
    item: unknown;
    bytes: number;
}>, request: ReferencePageRequest, readers: ReferenceReaders): Promise<ReferencePageResult & {
    count: number;
}>;
//# sourceMappingURL=assessment-projection.d.ts.map