@cleocode/core 2026.10.5 → 2026.10.6

package/dist/nexus/assessment-projection.js

@@ -38,6 +38,7 @@ function parseCount(flag, value) {
     if (value === undefined)
         return undefined;
     if (!/^\d+$/.test(value.trim()))
+        // @sync-invariant none:input-shape a malformed CLI flag is refused before any read; nothing is written
         throw new CleoError(ExitCode.INVALID_INPUT, `--${flag} must be a non-negative integer`, {
             fix: `cleo nexus status --${flag} <n>`,
             details: { field: flag, actual: value },
@@ -57,6 +58,7 @@ function parseCount(flag, value) {
 export function parseAssessmentFilesRequest(flags) {
     const status = flags.fileStatus?.trim();
     if (status !== undefined && !GRAPH_INDEX_FILE_STATUSES.some((known) => known === status))
+        // @sync-invariant none:input-shape a malformed CLI flag is refused before any read; nothing is written
         throw new CleoError(ExitCode.INVALID_INPUT, `--file-status must be one of ${GRAPH_INDEX_FILE_STATUSES.join(', ')}`, {
             fix: 'cleo nexus status --file-status failed',
             details: { field: 'file-status', actual: status },
@@ -140,4 +142,137 @@ export function projectAssessmentFiles(assessment, request = {}) {
         filesPage: pageFiles(files, request),
     };
 }
+/** References in the default page of `assessment.referencesPage` (T13330). */
+export 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 const MAX_REFERENCE_PAGE_SIZE = 5_000;
+/**
+ * Zero count for every reference kind. Typed as the contract's
+ * `Record<kind, number>`, so the compiler rejects a missing or unknown kind:
+ * the kind list below is derived from it and cannot drift from the contract.
+ */
+const EMPTY_REFERENCE_KIND_COUNTS = {
+    'unmodeled-source': 0,
+    ambiguous: 0,
+    external: 0,
+    dynamic: 0,
+    shadowed: 0,
+    unresolved: 0,
+};
+/** Whether `value` names a contract reference kind. */
+function isReferenceKind(value) {
+    return Object.hasOwn(EMPTY_REFERENCE_KIND_COUNTS, value);
+}
+/** Every reference limitation kind, derived from the contract's kind counts. */
+export const GRAPH_INDEX_REFERENCE_KINDS = Object.keys(EMPTY_REFERENCE_KIND_COUNTS).filter(isReferenceKind);
+/**
+ * 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 function parseReferencePageRequest(flags) {
+    const kind = flags.kind?.trim();
+    if (kind !== undefined && !GRAPH_INDEX_REFERENCE_KINDS.some((known) => known === kind))
+        // @sync-invariant none:input-shape a malformed CLI flag is refused before any read; nothing is written
+        throw new CleoError(ExitCode.INVALID_INPUT, `--reference-kind must be one of ${GRAPH_INDEX_REFERENCE_KINDS.join(', ')}`, {
+            fix: 'cleo nexus status --references --reference-kind unresolved',
+            details: { field: 'reference-kind', actual: kind },
+        });
+    const limit = parseCount('references-limit', flags.limit) ?? DEFAULT_REFERENCE_PAGE_SIZE;
+    if (limit < 1 || limit > MAX_REFERENCE_PAGE_SIZE)
+        // @sync-invariant none:input-shape a malformed CLI flag is refused before any read; nothing is written
+        throw new CleoError(ExitCode.INVALID_INPUT, `--references-limit must be from 1 to ${MAX_REFERENCE_PAGE_SIZE}; walk the whole list ` +
+            'with --references-offset <referencesPage.nextOffset>', {
+            fix: `cleo nexus status --references --references-limit ${MAX_REFERENCE_PAGE_SIZE} --references-offset 0`,
+            details: { field: 'references-limit', actual: flags.limit },
+        });
+    return {
+        limit,
+        offset: parseCount('references-offset', flags.offset) ?? 0,
+        ...(kind === undefined
+            ? {}
+            : { kind: GRAPH_INDEX_REFERENCE_KINDS.find((known) => known === kind) }),
+    };
+}
+/**
+ * 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 function withReferencePage(projection, result) {
+    const { references: _references, ...rest } = projection;
+    return {
+        ...rest,
+        _withheld: { ...projection._withheld, references: result.bytes },
+        referencesByKind: result.byKind,
+        referencesPage: result.page,
+    };
+}
+/**
+ * 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 async function pageReferences(items, request, readers) {
+    const byKind = { ...EMPTY_REFERENCE_KIND_COUNTS };
+    const rows = [];
+    let count = 0;
+    let matching = 0;
+    let bytes = 0;
+    for await (const { item, bytes: size } of items) {
+        const kind = readers.kind(item);
+        byKind[kind] += 1;
+        count += 1;
+        bytes += size;
+        if (request.kind !== undefined && kind !== request.kind)
+            continue;
+        if (matching >= request.offset && rows.length < request.limit)
+            rows.push(readers.row(item));
+        matching += 1;
+    }
+    const end = Math.min(request.offset + request.limit, matching);
+    return {
+        count,
+        byKind,
+        bytes: bytes + 2 + Math.max(count - 1, 0),
+        page: {
+            offset: request.offset,
+            limit: request.limit,
+            ...(request.kind === undefined ? {} : { kind: request.kind }),
+            total: matching,
+            returned: rows.length,
+            nextOffset: end < matching ? end : null,
+            rows,
+        },
+    };
+}
 //# sourceMappingURL=assessment-projection.js.map

package/dist/nexus/assessment-projection.js.map

@@ -1 +1 @@
-{"version":3,"file":"assessment-projection.js","sourceRoot":"","sources":["../../src/nexus/assessment-projection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,0DAA0D;AAC1D,MAAM,CAAC,MAAM,iCAAiC,GAAG,EAAE,CAAC;AAEpD,sDAAsD;AACtD,MAAM,CAAC,MAAM,yBAAyB,GAAoC;IACxE,UAAU;IACV,UAAU;IACV,aAAa;IACb,WAAW;IACX,QAAQ;CACT,CAAC;AA0BF;;;GAGG;AACH,SAAS,UAAU,CAAC,IAAY,EAAE,KAAyB;IACzD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,aAAa,EAAE,KAAK,IAAI,iCAAiC,EAAE;YACtF,GAAG,EAAE,uBAAuB,IAAI,MAAM;YACtC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE;SACxC,CAAC,CAAC;IACL,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAA2B;IACrE,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;IACxC,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,CAAC;QACtF,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,aAAa,EACtB,gCAAgC,yBAAyB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACtE;YACE,GAAG,EAAE,wCAAwC;YAC7C,OAAO,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE;SAClD,CACF,CAAC;IACJ,OAAO;QACL,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;QACjF,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QACrF,GAAG,CAAC,MAAM,KAAK,SAAS;YACtB,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,MAAM,EAAE,yBAAyB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,CAAC,EAAE,CAAC;KAC7E,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,cAAc,CAAC,IAAqC;IAC3D,IAAI,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7C,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,KAAK,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IAChF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,gBAAgB;AAChB,SAAS,aAAa,CAAC,IAAqC;IAC1D,MAAM,MAAM,GAA+B;QACzC,QAAQ,EAAE,CAAC;QACX,QAAQ,EAAE,CAAC;QACX,WAAW,EAAE,CAAC;QACd,SAAS,EAAE,CAAC;QACZ,MAAM,EAAE,CAAC;KACV,CAAC;IACF,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,gBAAgB;AAChB,SAAS,SAAS,CAChB,IAAqC,EACrC,OAA+B;IAE/B,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7F,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,iCAAiC,CAAC,CAAC;IACpF,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACpF,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO;QACL,MAAM;QACN,KAAK,EAAE,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI;QAC/B,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,KAAK,EAAE,QAAQ,CAAC,MAAM;QACtB,QAAQ,EAAE,IAAI,CAAC,MAAM;QACrB,UAAU,EAAE,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI;QAC9C,IAAI,EAAE,IAAI;KACX,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAgC,EAChC,UAAkC,EAAE;IAEpC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI,EAAE,GAAG,UAAU,CAAC;IACtC,MAAM,OAAO,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;IACjF,MAAM,QAAQ,GACZ,CAAC,OAAO,CAAC,GAAG,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;IACtF,IAAI,QAAQ;QAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,OAAO,EAAE,KAAK,EAAE,CAAC;IACpD,OAAO;QACL,SAAS,EAAE,EAAE,KAAK,EAAE,cAAc,CAAC,KAAK,CAAC,EAAE;QAC3C,GAAG,IAAI;QACP,GAAG,OAAO;QACV,SAAS,EAAE,SAAS,CAAC,KAAK,EAAE,OAAO,CAAC;KACrC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"assessment-projection.js","sourceRoot":"","sources":["../../src/nexus/assessment-projection.ts"],"names":[],"mappings":"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"}

package/dist/nexus/assessment-store.d.ts

@@ -20,6 +20,14 @@
  * ~0.6 s to compress and ~0.55 s to inflate. A historical plain-text list is
  * still read as stored.
  *
+ * The list is written one reference per line, in gzip members of
+ * {@link REFERENCES_PER_MEMBER} references, and read back line by line
+ * (T13326). Building it as ONE `JSON.stringify` string failed outright on a
+ * 5 357-file repository: 846 151 references exceed V8's maximum string length
+ * (2^29 - 24 characters), so publication died with "Invalid string length"
+ * after every other phase had finished. The text is still one valid JSON
+ * array, so a reader that parses it whole keeps working for lists that fit.
+ *
  * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
  *
  * @task T12348
@@ -34,10 +42,56 @@ export declare const ASSESSMENT_REFERENCES_KEY = "graph_assessment_references";
 /**
  * Encode a reference list for storage under {@link ASSESSMENT_REFERENCES_KEY}.
  *
+ * The decompressed text is the JSON array `[\n<ref>,\n<ref>\n]` — one
+ * reference per line — written as concatenated gzip members, so no string
+ * longer than one member's text is ever built (T13326).
+ *
  * @param references - The generation's retained references.
  * @returns gzip-compressed JSON, stored as a BLOB.
  */
 export declare function encodeStoredReferences(references: readonly GraphIndexReferenceReport[]): Uint8Array;
+/**
+ * Parse a stored reference list into its items without building one string
+ * of the whole list (T13326).
+ *
+ * Reads the line-per-reference form written by {@link encodeStoredReferences},
+ * and the single-line form written before it — compressed or plain text —
+ * by parsing that one line whole, as it was always read.
+ *
+ * @param value - The raw `_nexus_meta.value` of {@link ASSESSMENT_REFERENCES_KEY}.
+ * @returns The stored items, not yet validated.
+ * @throws When the value is neither text nor a compressed list, or is not a JSON array.
+ * @example
+ * ```ts
+ * const references = z.array(referenceSchema).parse(parseStoredReferences(row.value));
+ * ```
+ */
+export declare function parseStoredReferences(value: unknown): unknown[];
+/** One stored reference, not yet validated, and the UTF-8 size of its JSON. */
+export interface StoredReferenceItem {
+    /** The parsed reference. */
+    item: unknown;
+    /** UTF-8 bytes of the reference's own JSON text. */
+    bytes: number;
+}
+/**
+ * Stream a stored reference list one reference at a time (T13330).
+ *
+ * The compressed list is inflated incrementally and split on line breaks, so
+ * neither the decompressed text nor the parsed list is ever held whole: a
+ * reader that keeps one page holds one page. The single-line form written
+ * before T13326 has no line breaks to split on; it was small enough to be
+ * written whole, so it is parsed whole, as it was always read.
+ *
+ * @param value - The raw `_nexus_meta.value` of {@link ASSESSMENT_REFERENCES_KEY}.
+ * @returns The stored references in stored order.
+ * @throws When the value is neither text nor a compressed list, or is not a JSON array.
+ * @example
+ * ```ts
+ * for await (const { item } of streamStoredReferences(row.value)) count++;
+ * ```
+ */
+export declare function streamStoredReferences(value: unknown): AsyncGenerator<StoredReferenceItem, void, undefined>;
 /**
  * Decode a stored reference list back to its JSON text.
  *

package/dist/nexus/assessment-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assessment-store.d.ts","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mDAAmD;AACnD,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAKvE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,yBAAyB,EAAE,GAC/C,UAAU,CAEZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,GAAG,oBAAoB,CAIxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,EACnC,UAAU,EAAE,oBAAoB,GAC/B,oBAAoB,CAWtB;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAMhG"}
+{"version":3,"file":"assessment-store.d.ts","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAE3F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,mDAAmD;AACnD,eAAO,MAAM,cAAc,qBAAqB,CAAC;AAEjD,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,gCAAgC,CAAC;AAiBvE;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,SAAS,yBAAyB,EAAE,GAC/C,UAAU,CAYZ;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,EAAE,CA0B/D;AAED,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,oDAAoD;IACpD,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAuB,sBAAsB,CAC3C,KAAK,EAAE,OAAO,GACb,cAAc,CAAC,mBAAmB,EAAE,IAAI,EAAE,SAAS,CAAC,CAqDtD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,GAAG,oBAAoB,CAIxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,CAAC,EACnC,UAAU,EAAE,oBAAoB,GAC/B,oBAAoB,CAWtB;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAAC,EAAE,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAAG,OAAO,CAMhG"}

package/dist/nexus/assessment-store.js

@@ -20,13 +20,22 @@
  * ~0.6 s to compress and ~0.55 s to inflate. A historical plain-text list is
  * still read as stored.
  *
+ * The list is written one reference per line, in gzip members of
+ * {@link REFERENCES_PER_MEMBER} references, and read back line by line
+ * (T13326). Building it as ONE `JSON.stringify` string failed outright on a
+ * 5 357-file repository: 846 151 references exceed V8's maximum string length
+ * (2^29 - 24 characters), so publication died with "Invalid string length"
+ * after every other phase had finished. The text is still one valid JSON
+ * array, so a reader that parses it whole keeps working for lists that fit.
+ *
  * Code placed in `packages/core/` per Package-Boundary Check — verified against AGENTS.md.
  *
  * @task T12348
  * @module nexus/assessment-store
  */
 import { isAbsolute } from 'node:path';
-import { gunzipSync, gzipSync } from 'node:zlib';
+import { Readable } from 'node:stream';
+import { createGunzip, gunzipSync, gzipSync } from 'node:zlib';
 import { sql } from 'drizzle-orm';
 import { encodeStoredAssessment } from './stored-roots.js';
 /** `_nexus_meta` key of the assessment summary. */
@@ -35,14 +44,164 @@ export const ASSESSMENT_KEY = 'graph_assessment';
 export const ASSESSMENT_REFERENCES_KEY = 'graph_assessment_references';
 /** gzip level of the stored reference list: level 1 is ~16x smaller at ~1 s per 450 MB. */
 const REFERENCES_GZIP_LEVEL = 1;
+/**
+ * References compressed per gzip member of the stored list.
+ *
+ * Bounds the largest string the encoder builds to one member's worth (a few
+ * MB) whatever the repository size, while keeping members large enough that
+ * per-member gzip framing does not cost compression.
+ */
+const REFERENCES_PER_MEMBER = 4096;
+/** Newline byte; JSON text never contains a raw one inside a value. */
+const NEWLINE = 0x0a;
 /**
  * Encode a reference list for storage under {@link ASSESSMENT_REFERENCES_KEY}.
  *
+ * The decompressed text is the JSON array `[\n<ref>,\n<ref>\n]` — one
+ * reference per line — written as concatenated gzip members, so no string
+ * longer than one member's text is ever built (T13326).
+ *
  * @param references - The generation's retained references.
  * @returns gzip-compressed JSON, stored as a BLOB.
  */
 export function encodeStoredReferences(references) {
-    return gzipSync(JSON.stringify(references), { level: REFERENCES_GZIP_LEVEL });
+    const members = [];
+    let text = '[';
+    references.forEach((reference, index) => {
+        text += `${index === 0 ? '\n' : ',\n'}${JSON.stringify(reference)}`;
+        if ((index + 1) % REFERENCES_PER_MEMBER === 0) {
+            members.push(gzipSync(text, { level: REFERENCES_GZIP_LEVEL }));
+            text = '';
+        }
+    });
+    members.push(gzipSync(`${text}\n]`, { level: REFERENCES_GZIP_LEVEL }));
+    return Buffer.concat(members);
+}
+/**
+ * Parse a stored reference list into its items without building one string
+ * of the whole list (T13326).
+ *
+ * Reads the line-per-reference form written by {@link encodeStoredReferences},
+ * and the single-line form written before it — compressed or plain text —
+ * by parsing that one line whole, as it was always read.
+ *
+ * @param value - The raw `_nexus_meta.value` of {@link ASSESSMENT_REFERENCES_KEY}.
+ * @returns The stored items, not yet validated.
+ * @throws When the value is neither text nor a compressed list, or is not a JSON array.
+ * @example
+ * ```ts
+ * const references = z.array(referenceSchema).parse(parseStoredReferences(row.value));
+ * ```
+ */
+export function parseStoredReferences(value) {
+    let bytes;
+    if (typeof value === 'string')
+        bytes = Buffer.from(value, 'utf8');
+    else if (value instanceof Uint8Array)
+        bytes = gunzipSync(value);
+    // @sync-invariant none:input-shape a malformed stored list is refused on read; nothing is written
+    else
+        throw new Error('Graph reference metadata is neither text nor a compressed list.');
+    const firstBreak = bytes.indexOf(NEWLINE);
+    if (firstBreak === -1 || bytes.toString('utf8', 0, firstBreak).trim() !== '[') {
+        const whole = JSON.parse(bytes.toString('utf8'));
+        // @sync-invariant none:input-shape a malformed stored list is refused on read; nothing is written
+        if (!Array.isArray(whole))
+            throw new Error('Graph reference metadata is not a list.');
+        return whole;
+    }
+    const items = [];
+    let start = firstBreak + 1;
+    while (start < bytes.length) {
+        const end = bytes.indexOf(NEWLINE, start);
+        const line = bytes
+            .toString('utf8', start, end === -1 ? bytes.length : end)
+            .trim()
+            .replace(/,$/, '');
+        if (line !== ']' && line !== '')
+            items.push(JSON.parse(line));
+        if (end === -1)
+            break;
+        start = end + 1;
+    }
+    return items;
+}
+/**
+ * Stream a stored reference list one reference at a time (T13330).
+ *
+ * The compressed list is inflated incrementally and split on line breaks, so
+ * neither the decompressed text nor the parsed list is ever held whole: a
+ * reader that keeps one page holds one page. The single-line form written
+ * before T13326 has no line breaks to split on; it was small enough to be
+ * written whole, so it is parsed whole, as it was always read.
+ *
+ * @param value - The raw `_nexus_meta.value` of {@link ASSESSMENT_REFERENCES_KEY}.
+ * @returns The stored references in stored order.
+ * @throws When the value is neither text nor a compressed list, or is not a JSON array.
+ * @example
+ * ```ts
+ * for await (const { item } of streamStoredReferences(row.value)) count++;
+ * ```
+ */
+export async function* streamStoredReferences(value) {
+    let source;
+    if (typeof value === 'string')
+        source = Readable.from([Buffer.from(value, 'utf8')]);
+    else if (value instanceof Uint8Array)
+        source = Readable.from([value]).pipe(createGunzip());
+    // @sync-invariant none:input-shape a malformed stored list is refused on read; nothing is written
+    else
+        throw new Error('Graph reference metadata is neither text nor a compressed list.');
+    // Unterminated bytes, kept as chunks and joined once per line (T13372): a
+    // join per CHUNK, then a rescan of the whole buffer, made a long line —
+    // the legacy single-line list is one line — cost quadratic time.
+    let parts = [];
+    let legacy = false;
+    let sawOpening = false;
+    for await (const chunk of source) {
+        if (legacy) {
+            parts.push(chunk);
+            continue;
+        }
+        let start = 0;
+        for (let end = chunk.indexOf(NEWLINE); end !== -1; end = chunk.indexOf(NEWLINE, start)) {
+            const lineBytes = parts.length === 0
+                ? chunk.subarray(start, end)
+                : Buffer.concat([...parts, chunk.subarray(start, end)]);
+            parts = [];
+            const line = lineBytes.toString('utf8').trim();
+            if (!sawOpening) {
+                if (line !== '[') {
+                    // Not the line-per-reference form: keep every byte for a whole parse.
+                    legacy = true;
+                    parts = [lineBytes, chunk.subarray(end)];
+                    break;
+                }
+                sawOpening = true;
+            }
+            else {
+                const text = line.replace(/,$/, '');
+                if (text !== ']' && text !== '')
+                    yield { item: JSON.parse(text), bytes: Buffer.byteLength(text, 'utf8') };
+            }
+            start = end + 1;
+        }
+        if (!legacy && start < chunk.length)
+            parts.push(chunk.subarray(start));
+    }
+    const rest = Buffer.concat(parts).toString('utf8').trim();
+    if (sawOpening && !legacy) {
+        const text = rest.replace(/,$/, '');
+        if (text !== ']' && text !== '')
+            yield { item: JSON.parse(text), bytes: Buffer.byteLength(text, 'utf8') };
+        return;
+    }
+    const whole = JSON.parse(rest);
+    // @sync-invariant none:input-shape a malformed stored list is refused on read; nothing is written
+    if (!Array.isArray(whole))
+        throw new Error('Graph reference metadata is not a list.');
+    for (const item of whole)
+        yield { item, bytes: Buffer.byteLength(JSON.stringify(item), 'utf8') };
 }
 /**
  * Decode a stored reference list back to its JSON text.

package/dist/nexus/assessment-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"assessment-store.js","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEjD,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAElC,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,mDAAmD;AACnD,MAAM,CAAC,MAAM,cAAc,GAAG,kBAAkB,CAAC;AAEjD,iEAAiE;AACjE,MAAM,CAAC,MAAM,yBAAyB,GAAG,6BAA6B,CAAC;AAEvE,2FAA2F;AAC3F,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAgD;IAEhD,OAAO,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc;IACnD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,UAAU;QAAE,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3E,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAAgC;IAChE,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS;QAAE,OAAO,UAAU,CAAC;IAC3D,MAAM,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,GAAG,UAAU,CAAC;IAC9C,OAAO,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,EAAmC,EACnC,UAAgC;IAEhC,MAAM,OAAO,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;IAC9C,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,qDAAqD,cAAc,KAAK,IAAI,CAAC,SAAS,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC;8FACrC,CAAC,CAAC;IAC9F,IAAI,UAAU,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QACxC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,qDAAqD,yBAAyB,KAAK,sBAAsB,CAAC,UAAU,CAAC,UAAU,CAAC;gGAC9C,CAAC,CAAC;IAChG,CAAC;SAAM,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QAChD,EAAE,CAAC,GAAG,CAAC,GAAG,CAAA,4CAA4C,yBAAyB,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gCAAgC,CAAC,EAAsC;IACrF,MAAM,GAAG,GAAG,EAAE,CAAC,MAAM,CACnB,GAAG,CAAA;0CACmC,cAAc,EAAE,CACvD,CAAC,CAAC,CAAC,CAAC;IACL,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;AAClF,CAAC"}
+{"version":3,"file":"assessment-store.js","sourceRoot":"","sources":["../../src/nexus/assessment-store.ts"],"names":[],"mappings":"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"}

package/dist/nexus/knowledge.d.ts

@@ -5,6 +5,7 @@
  * against AGENTS.md. These services do not invoke a language model.
  */
 import type { GraphIndexAssessment, GraphIndexReferenceReport, KnowledgeCoverage, KnowledgeCoverageStatus, KnowledgeSymbolCandidate } from '@cleocode/contracts';
+import { type ReferencePageRequest, type ReferencePageResult } from './assessment-projection.js';
 /**
  * Read validated generation provenance without treating malformed metadata as healthy.
  *
@@ -41,6 +42,24 @@ export declare function readKnowledgeIndexAssessment(projectRoot?: string): Prom
  * ```
  */
 export declare function readKnowledgeIndexReferences(projectRoot?: string): Promise<GraphIndexReferenceReport[] | null>;
+/**
+ * Read one page of the published generation's retained references, with the
+ * per-kind totals of the whole list (T13330).
+ *
+ * The stored list is streamed: every reference is parsed to count its kind and
+ * then dropped, and only the requested page is kept and fully validated. A
+ * status call therefore holds one page however many references the repository
+ * has — 846 151 on one 5 357-file project, over 500 MB as a single JSON value.
+ * @param projectRoot - Explicit project root, or the ambient canonical project when omitted.
+ * @param request - Page size, offset and optional kind filter.
+ * @returns The page and totals; `null` when no graph is published.
+ * @throws When the stored list is malformed or disagrees with the recorded count.
+ * @example
+ * ```ts
+ * const result = await readKnowledgeIndexReferencePage(root, { limit: 20, offset: 0 });
+ * ```
+ */
+export declare function readKnowledgeIndexReferencePage(projectRoot: string | undefined, request: ReferencePageRequest): Promise<ReferencePageResult | null>;
 /**
  * An unresolved short name with exact identifiers the caller can choose from.
  * @remarks Consumers preserve the candidate list in their error envelope.

package/dist/nexus/knowledge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/nexus/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,KAAK,EACV,oBAAoB,EAEpB,yBAAyB,EACzB,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AA+N7B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAyBtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,yBAAyB,EAAE,GAAG,IAAI,CAAC,CAkB7C;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,wBAAwB;IAErC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,wBAAwB,EAAE,CAAC;IAEhD;;;;OAIG;gBACS,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,wBAAwB,EAAE;CAKlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,wBAAwB,EAAE,GACzC,wBAAwB,GAAG,IAAI,CAWjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,uBAAuB,EAC/B,MAAM,EAAE,MAAM,GACb,IAAI,CAUN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,SAAO,GACd,OAAO,CAAC,iBAAiB,CAAC,CAS5B"}
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../src/nexus/knowledge.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,KAAK,EACV,oBAAoB,EAEpB,yBAAyB,EACzB,iBAAiB,EACjB,uBAAuB,EACvB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAO7B,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,4BAA4B,CAAC;AA2NpC;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAyBtC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,4BAA4B,CAChD,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,yBAAyB,EAAE,GAAG,IAAI,CAAC,CAkB7C;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,+BAA+B,CACnD,WAAW,EAAE,MAAM,GAAG,SAAS,EAC/B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CA8BrC;AAED;;;;;;;GAOG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IACtD,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,wBAAwB;IAErC,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,wBAAwB,EAAE,CAAC;IAEhD;;;;OAIG;gBACS,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,wBAAwB,EAAE;CAKlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,SAAS,wBAAwB,EAAE,GACzC,wBAAwB,GAAG,IAAI,CAWjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,iBAAiB,EAC3B,MAAM,EAAE,uBAAuB,EAC/B,MAAM,EAAE,MAAM,GACb,IAAI,CAUN;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,uBAAuB,CAC3C,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,SAAO,GACd,OAAO,CAAC,iBAAiB,CAAC,CAS5B"}

package/dist/nexus/knowledge.js

@@ -16,7 +16,8 @@ import { z } from 'zod';
 import { getProjectRoot, worktreeScope } from '../paths.js';
 import { getProjectInfoSync } from '../project-info.js';
 import { getNexusDb, getNexusNativeDb, nexusSchema } from '../store/nexus-sqlite.js';
-import { ASSESSMENT_KEY, ASSESSMENT_REFERENCES_KEY, decodeStoredReferences, } from './assessment-store.js';
+import { pageReferences, } from './assessment-projection.js';
+import { ASSESSMENT_KEY, ASSESSMENT_REFERENCES_KEY, parseStoredReferences, streamStoredReferences, } from './assessment-store.js';
 import { generateProjectHash } from './hash.js';
 import { resolveSourceRoots } from './source-roots.js';
 import { decodeStoredAssessment, describeGraphOwnershipMismatch, graphOwnershipRemedy, } from './stored-roots.js';
@@ -274,11 +275,64 @@ export async function readKnowledgeIndexReferences(projectRoot) {
             throw new Error('Graph assessment reports references, but none are stored.');
         return [];
     }
-    const references = z.array(referenceSchema).parse(JSON.parse(decodeStoredReferences(row.value)));
+    const references = z.array(referenceSchema).parse(parseStoredReferences(row.value));
     if (assessment.referenceCount !== undefined && references.length !== assessment.referenceCount)
         throw new Error('Stored graph references disagree with the assessment reference count.');
     return references;
 }
+/** The one field a reference's kind count needs; the page rows get the full schema. */
+const referenceKindSchema = z.object({ kind: referenceSchema.shape.kind });
+/**
+ * Read one page of the published generation's retained references, with the
+ * per-kind totals of the whole list (T13330).
+ *
+ * The stored list is streamed: every reference is parsed to count its kind and
+ * then dropped, and only the requested page is kept and fully validated. A
+ * status call therefore holds one page however many references the repository
+ * has — 846 151 on one 5 357-file project, over 500 MB as a single JSON value.
+ * @param projectRoot - Explicit project root, or the ambient canonical project when omitted.
+ * @param request - Page size, offset and optional kind filter.
+ * @returns The page and totals; `null` when no graph is published.
+ * @throws When the stored list is malformed or disagrees with the recorded count.
+ * @example
+ * ```ts
+ * const result = await readKnowledgeIndexReferencePage(root, { limit: 20, offset: 0 });
+ * ```
+ */
+export async function readKnowledgeIndexReferencePage(projectRoot, request) {
+    const assessment = await readKnowledgeIndexAssessment(projectRoot);
+    if (!assessment)
+        return null;
+    let items;
+    if (assessment.references) {
+        items = assessment.references.map((item) => ({
+            item,
+            bytes: Buffer.byteLength(JSON.stringify(item), 'utf8'),
+        }));
+    }
+    else {
+        const native = getNexusNativeDb(projectRoot);
+        // @sync-invariant none:input-shape a read of the stored reference list refuses malformed state; nothing is written
+        if (!native)
+            throw new Error('The graph database is unavailable.');
+        const row = native
+            .prepare('SELECT value FROM main._nexus_meta WHERE key = ?')
+            .get(ASSESSMENT_REFERENCES_KEY);
+        if (!row && (assessment.referenceCount ?? 0) > 0)
+            // @sync-invariant none:input-shape a read of the stored reference list refuses malformed state; nothing is written
+            throw new Error('Graph assessment reports references, but none are stored.');
+        items = row ? streamStoredReferences(row.value) : [];
+    }
+    const result = await pageReferences(items, request, {
+        kind: (item) => referenceKindSchema.parse(item).kind,
+        row: (item) => referenceSchema.parse(item),
+    });
+    if (assessment.referenceCount !== undefined && result.count !== assessment.referenceCount)
+        // @sync-invariant none:input-shape a read of the stored reference list refuses malformed state; nothing is written
+        throw new Error('Stored graph references disagree with the assessment reference count.');
+    const { count: _count, ...page } = result;
+    return page;
+}
 /**
  * An unresolved short name with exact identifiers the caller can choose from.
  * @remarks Consumers preserve the candidate list in their error envelope.