@moldea.ai/core 3.1.0 → 4.0.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as CoreOperationException, t as CoreConfigurationException } from "./chunks/exceptions-DWsZTpqs.js";
+import { n as CoreOperationException, t as CoreConfigurationException } from "./chunks/exceptions-C_KfCIjE.js";
 import { REPOSITORY_ROOT, RepositoryPathException, RepositorySourceException, compareRepositoryPaths, createRepositoryIdentity, isRepositoryPath, parseRepositoryPath } from "@moldea.ai/repository";
 import { Parser, isAlias, isMap, isScalar, isSeq, parseAllDocuments } from "yaml";
 //#region src/constants/index.ts
@@ -22,6 +22,7 @@ var DEFAULT_CORE_RESOURCE_LIMITS = Object.freeze({
 	maxEvidence: 1e4,
 	maxFileBytes: 8388608,
 	maxManifestBytes: 2097152,
+	maxRetainedBytes: 536870912,
 	maxTotalBytesRead: 134217728
 });
 //#endregion
@@ -142,6 +143,9 @@ var readCanonicalContentPage = async (input, options) => {
 	if (entry.byteLength > options.limits.maxFileBytes) throw new CoreOperationException({
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit: "maxFileBytes",
+		limitMaximum: options.limits.maxFileBytes,
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage: entry.byteLength,
 		operation: "read-canonical-content-page"
 	});
 	if (input.offset > entry.byteLength) return invalidArgument$4();
@@ -443,6 +447,9 @@ var registerCoreDiagnosticCandidates = (limits, amount, operation, fallbackCount
 		...adapterId === void 0 ? {} : { adapterId },
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit: "maxDiagnostics",
+		limitMaximum: limits.maxDiagnostics,
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage: currentCount + amount,
 		operation
 	});
 	if (budget !== void 0) budget.count += amount;
@@ -788,6 +795,7 @@ var RESOURCE_LIMIT_KEYS = [
 	"maxTotalBytesRead",
 	"maxFileBytes",
 	"maxManifestBytes",
+	"maxRetainedBytes",
 	"maxDiagnostics",
 	"maxEvidence"
 ];
@@ -964,7 +972,7 @@ var createSourceLocator = (value) => {
 };
 //#endregion
 //#region src/text/index.ts
-var encoder$1 = new TextEncoder();
+var encoder$2 = new TextEncoder();
 var decoder = new TextDecoder("utf-8", {
 	fatal: true,
 	ignoreBOM: true
@@ -1053,6 +1061,9 @@ var enforceFileLimit = (byteLength, limits, operation, limit) => {
 	throw new CoreOperationException({
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit,
+		limitMaximum: limits[limit],
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage: byteLength,
 		operation
 	});
 };
@@ -1135,7 +1146,7 @@ var normalizeTextDocument = (input, limits, operation, limit = "maxFileBytes") =
 		diagnostics: [],
 		text: freezeRecursively({
 			scalarLength: countUnicodeScalars(value),
-			utf8ByteLength: encoder$1.encode(value).byteLength,
+			utf8ByteLength: encoder$2.encode(value).byteLength,
 			value
 		}),
 		valid: true
@@ -1152,7 +1163,7 @@ var toLowercaseHex = (bytes) => {
 * @returns A promise resolving to the canonical lowercase SHA-256 digest.
 */
 var calculateNormalizedTextDigest = async (text) => {
-	const bytes = encoder$1.encode(text.value);
+	const bytes = encoder$2.encode(text.value);
 	return `sha256:${toLowercaseHex(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes)))}`;
 };
 /**
@@ -2472,6 +2483,9 @@ var registerRawOutput = (outputCounts, key, amount, context) => {
 		adapterId: context.adapterId,
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit,
+		limitMaximum: context.limits[limit],
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage: outputCounts[key] + amount,
 		operation: "validate-adapter"
 	});
 	outputCounts[key] += amount;
@@ -2837,6 +2851,10 @@ var inspectRuntimeAdapters = async (project, session, options, signal) => {
 var MANIFEST_PATH$3 = parseRepositoryPath("/moldea/moldea.yaml");
 var SOURCE_PAGE_ENTRIES = 256;
 var SOURCE_PAGE_BYTES = 65536;
+var CANONICAL_BYTE_RETENTION_MULTIPLIER = 4;
+var RETAINED_PATH_FIXED_BYTES = 64;
+var RETAINED_PATH_BYTE_MULTIPLIER = 2;
+var encoder$1 = new TextEncoder();
 var invalidSourceData$3 = (operation, path) => {
 	throw new RepositorySourceException({
 		code: "INVALID_SOURCE_DATA",
@@ -2869,10 +2887,13 @@ var isStrictDescendant = (path, prefix) => {
 	const descendantPrefix = prefix === REPOSITORY_ROOT ? REPOSITORY_ROOT : `${prefix}/`;
 	return path.startsWith(descendantPrefix);
 };
-var throwResourceLimitExceeded = (limit) => {
+var throwResourceLimitExceeded = (limit, limitMaximum, observedUsage) => {
 	throw new CoreOperationException({
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit,
+		limitMaximum,
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage,
 		operation: "validate-project"
 	});
 };
@@ -2891,6 +2912,9 @@ var createSourceOptions = (sessionSignal, operationSignal) => {
 */
 var createRepositoryInspectionSession = (repository, limits, signal) => {
 	const seenPaths = /* @__PURE__ */ new Set();
+	let canonicalBytes = 0;
+	let peakRetainedBytes = 0;
+	let retainedBytes = 0;
 	let totalBytesRead = 0;
 	const adapterLimits = Object.freeze({
 		maxEntries: limits.maxEntries,
@@ -2906,9 +2930,19 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 			operation: "validate-project"
 		});
 	};
+	const reserveRetainedBytes = (byteLength) => {
+		if (!Number.isSafeInteger(byteLength) || byteLength < 0 || byteLength > limits.maxRetainedBytes - retainedBytes) return throwResourceLimitExceeded("maxRetainedBytes", limits.maxRetainedBytes, retainedBytes + byteLength);
+		retainedBytes += byteLength;
+		peakRetainedBytes = Math.max(peakRetainedBytes, retainedBytes);
+	};
+	const observeTransientBytes = (byteLength) => {
+		if (!Number.isSafeInteger(byteLength) || byteLength < 0 || byteLength > limits.maxRetainedBytes - retainedBytes) return throwResourceLimitExceeded("maxRetainedBytes", limits.maxRetainedBytes, retainedBytes + byteLength);
+		peakRetainedBytes = Math.max(peakRetainedBytes, retainedBytes + byteLength);
+	};
 	const registerPath = (path) => {
 		if (path === REPOSITORY_ROOT || seenPaths.has(path)) return;
-		if (seenPaths.size >= limits.maxEntries) return throwResourceLimitExceeded("maxEntries");
+		if (seenPaths.size >= limits.maxEntries) return throwResourceLimitExceeded("maxEntries", limits.maxEntries, seenPaths.size + 1);
+		reserveRetainedBytes(RETAINED_PATH_FIXED_BYTES + encoder$1.encode(path).byteLength * RETAINED_PATH_BYTE_MULTIPLIER);
 		seenPaths.add(path);
 	};
 	const throwIfSignalAborted = (operationSignal) => {
@@ -2917,7 +2951,7 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 	};
 	throwIfSignalAborted();
 	const reserveReadBytes = (byteLength) => {
-		if (byteLength > limits.maxTotalBytesRead - totalBytesRead) return throwResourceLimitExceeded("maxTotalBytesRead");
+		if (byteLength > limits.maxTotalBytesRead - totalBytesRead) return throwResourceLimitExceeded("maxTotalBytesRead", limits.maxTotalBytesRead, totalBytesRead + byteLength);
 		totalBytesRead += byteLength;
 	};
 	const getEntry = async (path, options) => {
@@ -2964,15 +2998,29 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 	};
 	const loadFile = async (path, operationSignal) => {
 		const fileLimit = path === MANIFEST_PATH$3 ? "maxManifestBytes" : "maxFileBytes";
+		const availableRetainedBytes = limits.maxRetainedBytes - retainedBytes;
+		if (availableRetainedBytes < 1) return throwResourceLimitExceeded("maxRetainedBytes", limits.maxRetainedBytes, retainedBytes + 1);
+		const firstPageMaximumBytes = Math.min(SOURCE_PAGE_BYTES, Math.max(1, limits[fileLimit]), availableRetainedBytes);
+		observeTransientBytes(firstPageMaximumBytes);
 		const firstPage = await repository.readFilePage(path, {
-			maxBytes: Math.min(SOURCE_PAGE_BYTES, Math.max(1, limits[fileLimit])),
+			maxBytes: firstPageMaximumBytes,
 			offset: 0,
 			...createSourceOptions(signal, operationSignal) ?? {}
 		});
 		throwIfSignalAborted(operationSignal);
 		if (firstPage.snapshot.id !== repository.snapshot.id || firstPage.offset !== 0 || !(firstPage.bytes instanceof Uint8Array) || !Number.isSafeInteger(firstPage.totalBytes) || firstPage.totalBytes < 0 || firstPage.bytes.byteLength > SOURCE_PAGE_BYTES || firstPage.bytes.byteLength > firstPage.totalBytes || firstPage.bytes.byteLength === 0 && !firstPage.isComplete) return invalidSourceData$3("read-file-page", path);
-		if (firstPage.totalBytes > limits[fileLimit]) return throwResourceLimitExceeded(fileLimit);
+		if (firstPage.totalBytes > limits[fileLimit]) return throwResourceLimitExceeded(fileLimit, limits[fileLimit], firstPage.totalBytes);
+		const firstPageBytes = firstPage.bytes.byteLength;
+		const retainedBytesAvailableForCanonicalContent = limits.maxRetainedBytes - retainedBytes - firstPageBytes;
+		if (retainedBytesAvailableForCanonicalContent < 0 || firstPage.totalBytes > Math.floor(retainedBytesAvailableForCanonicalContent / CANONICAL_BYTE_RETENTION_MULTIPLIER)) {
+			const projectedUsage = retainedBytes + firstPageBytes + firstPage.totalBytes * CANONICAL_BYTE_RETENTION_MULTIPLIER;
+			return throwResourceLimitExceeded("maxRetainedBytes", limits.maxRetainedBytes, Number.isSafeInteger(projectedUsage) ? projectedUsage : Number.MAX_SAFE_INTEGER);
+		}
 		reserveReadBytes(firstPage.totalBytes);
+		const canonicalRetainedBytes = firstPage.totalBytes * CANONICAL_BYTE_RETENTION_MULTIPLIER;
+		observeTransientBytes(canonicalRetainedBytes + firstPageBytes);
+		reserveRetainedBytes(canonicalRetainedBytes);
+		canonicalBytes += firstPage.totalBytes;
 		const content = new Uint8Array(firstPage.totalBytes);
 		let offset = 0;
 		let page = firstPage;
@@ -3033,7 +3081,7 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 	const listAdapterEntriesPage = async (options) => {
 		const prefix = options.prefix === void 0 ? REPOSITORY_ROOT : parseRepositoryPath(options.prefix);
 		registerPath(prefix);
-		if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1 || options.maxEntries > adapterLimits.maxPageEntries) return throwResourceLimitExceeded("maxEntries");
+		if (!Number.isSafeInteger(options.maxEntries) || options.maxEntries < 1 || options.maxEntries > adapterLimits.maxPageEntries) return throwResourceLimitExceeded("maxEntries", adapterLimits.maxPageEntries, options.maxEntries);
 		throwIfSignalAborted(options.signal);
 		const page = await repository.listEntriesPage({
 			...options.cursor === void 0 ? {} : { cursor: options.cursor },
@@ -3064,7 +3112,8 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 		throwIfSignalAborted(options.signal);
 		registerPath(parsedPath);
 		const reservedBytes = Math.min(options.maxBytes, limits.maxTotalBytesRead - totalBytesRead);
-		if (reservedBytes < 1) return throwResourceLimitExceeded("maxTotalBytesRead");
+		if (reservedBytes < 1) return throwResourceLimitExceeded("maxTotalBytesRead", limits.maxTotalBytesRead, totalBytesRead + 1);
+		observeTransientBytes(reservedBytes);
 		reserveReadBytes(reservedBytes);
 		let page;
 		try {
@@ -3101,6 +3150,12 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 	});
 	return Object.freeze({
 		adapterRepository,
+		getResourceUsage: () => Object.freeze({
+			canonicalBytes,
+			peakRetainedBytes,
+			retainedBytes,
+			totalBytesRead
+		}),
 		reader: Object.freeze({
 			getEntry,
 			iterateEntries,
@@ -4846,6 +4901,7 @@ var validateProjectState = async (input, options) => {
 	}, operationOptions);
 	if (universal.project === null) return freezeRecursively({
 		project: null,
+		resourceUsage: session.getResourceUsage(),
 		result: {
 			diagnostics: universal.diagnostics,
 			evidence: [],
@@ -4859,6 +4915,7 @@ var validateProjectState = async (input, options) => {
 	const availabilityDiagnostics = validateRuntimeAdapterAvailability(universal.runtimeLocations, universal.project.formatVersion, operationOptions);
 	if (availabilityDiagnostics.length > 0) return freezeRecursively({
 		project: universal.project,
+		resourceUsage: session.getResourceUsage(),
 		result: {
 			diagnostics: availabilityDiagnostics,
 			evidence: [],
@@ -4872,6 +4929,7 @@ var validateProjectState = async (input, options) => {
 	const valid = adapterInspection.diagnostics.length === 0;
 	return freezeRecursively({
 		project: universal.project,
+		resourceUsage: session.getResourceUsage(),
 		result: {
 			diagnostics: adapterInspection.diagnostics,
 			evidence: adapterInspection.evidence,
@@ -4885,16 +4943,30 @@ var validateProjectState = async (input, options) => {
 /** Validates one project without returning canonical document bodies. */
 var validateProject = async (input, options) => (await validateProjectState(input, options)).result;
 //#endregion
-//#region src/project-inspection-page/index.ts
-var CURSOR_PREFIX = "core3";
+//#region src/project-inspection/index.ts
+var CURSOR_PREFIX = "core4";
+var PREPARED_FIXED_BYTES = 512;
+var PREPARED_ITEM_FIXED_BYTES = 64;
+var PREPARED_TEXT_BYTE_MULTIPLIER = 2;
+var PREPARED_VIEW_REFERENCE_BYTES = 8;
 var encoder = new TextEncoder();
 var invalidArgument$1 = () => {
 	throw new CoreOperationException({
 		code: "INVALID_ARGUMENT",
-		operation: "inspect-project-page"
+		operation: "create-project-inspection"
+	});
+};
+var resourceLimitExceeded$1 = (limitMaximum, observedUsage) => {
+	throw new CoreOperationException({
+		code: "RESOURCE_LIMIT_EXCEEDED",
+		limit: "maxRetainedBytes",
+		limitMaximum,
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage,
+		operation: "create-project-inspection"
 	});
 };
-/** Serializes the closed inspection records with recursively sorted object keys. */
+/** Serializes content-free inspection state with recursively sorted object keys. */
 var serializeDeterministically = (candidate) => {
 	if (candidate === null || typeof candidate !== "object") {
 		const serialized = JSON.stringify(candidate);
@@ -4933,7 +5005,7 @@ var createItemBaseKey = (item) => {
 		createIdentity([serializeDeterministically(item.evidence)])
 	].join(":");
 };
-/** Assigns stable unique keys without relying on collection offsets. */
+/** Assigns stable unique keys once without relying on collection offsets. */
 var createKeyedItems = (items) => {
 	const sorted = items.map((item) => ({
 		baseKey: createItemBaseKey(item),
@@ -4964,7 +5036,7 @@ var encodeCursor = (inspectionDigest, view, lastKey) => [
 ].join(":");
 var decodeCursor = (cursor, inspectionDigest, view) => {
 	if (cursor === void 0) return null;
-	const match = /^core3:(all|diagnostics|evidence|metadata):([^:]+):(sha256:[0-9a-f]{64}):(sha256:[0-9a-f]{64})$/u.exec(cursor);
+	const match = /^core4:(all|diagnostics|evidence|metadata):([^:]+):(sha256:[0-9a-f]{64}):(sha256:[0-9a-f]{64})$/u.exec(cursor);
 	if (match === null || match[1] !== view || match[3] !== inspectionDigest) return invalidArgument$1();
 	let lastKey;
 	try {
@@ -4975,20 +5047,112 @@ var decodeCursor = (cursor, inspectionDigest, view) => {
 	if (lastKey.length === 0 || match[4] !== createCursorChecksum(inspectionDigest, lastKey, view)) return invalidArgument$1();
 	return lastKey;
 };
-var selectViewItems = (items, view) => view === "all" ? items : items.filter(({ item }) => {
-	if (view === "diagnostics") return item.kind === "diagnostic";
-	return view === "metadata" ? item.kind === "metadata" || item.kind === "agent" : item.kind === view;
+var createViews = (items) => freezeRecursively({
+	all: items,
+	diagnostics: items.filter(({ item }) => item.kind === "diagnostic"),
+	evidence: items.filter(({ item }) => item.kind === "evidence"),
+	metadata: items.filter(({ item }) => item.kind === "metadata" || item.kind === "agent")
 });
-/** Returns one bounded content-free view over a completely validated project snapshot. */
-var inspectProjectPage = async (input, options) => {
-	if (typeof input !== "object" || input === null || Reflect.ownKeys(input).some((key) => key !== "cursor" && key !== "maxItems" && key !== "repository" && key !== "signal" && key !== "view") || !Number.isSafeInteger(input.maxItems) || input.maxItems < 1 || input.maxItems > options.limits.maxEntries || input.cursor !== void 0 && typeof input.cursor !== "string" || input.view !== "all" && input.view !== "diagnostics" && input.view !== "evidence" && input.view !== "metadata") return invalidArgument$1();
-	const state = await validateProjectState({
-		repository: input.repository,
-		...input.signal === void 0 ? {} : { signal: input.signal }
-	}, options);
+var addRetainedBytes = (current, additional, retainedBeforePreparation, maximum) => {
+	const projectedUsage = retainedBeforePreparation + current + additional;
+	if (!Number.isSafeInteger(additional) || additional < 0 || !Number.isSafeInteger(projectedUsage) || projectedUsage > maximum) return resourceLimitExceeded$1(maximum, Number.isSafeInteger(projectedUsage) ? projectedUsage : Number.MAX_SAFE_INTEGER);
+	return current + additional;
+};
+/** Calculates deterministic logical bytes retained by prepared records and view indexes. */
+var calculatePreparedBytes = (items, views, header, retainedBeforePreparation, maximum) => {
+	let bytes = addRetainedBytes(0, PREPARED_FIXED_BYTES, retainedBeforePreparation, maximum);
+	for (const { item, key } of items) {
+		const encodedBytes = encoder.encode(key).byteLength + encoder.encode(serializeDeterministically(item)).byteLength;
+		bytes = addRetainedBytes(bytes, PREPARED_ITEM_FIXED_BYTES + encodedBytes * PREPARED_TEXT_BYTE_MULTIPLIER, retainedBeforePreparation, maximum);
+	}
+	bytes = addRetainedBytes(bytes, encoder.encode(serializeDeterministically(header)).byteLength * PREPARED_TEXT_BYTE_MULTIPLIER, retainedBeforePreparation, maximum);
+	bytes = addRetainedBytes(bytes, (views.diagnostics.length + views.evidence.length + views.metadata.length) * PREPARED_VIEW_REFERENCE_BYTES, retainedBeforePreparation, maximum);
+	return bytes;
+};
+var findStartIndex = (items, lastKey) => {
+	if (lastKey === null) return 0;
+	let lower = 0;
+	let upper = items.length - 1;
+	while (lower <= upper) {
+		const middle = lower + Math.floor((upper - lower) / 2);
+		const candidate = items[middle];
+		if (candidate === void 0) return invalidArgument$1();
+		if (candidate.key === lastKey) return middle + 1;
+		if (candidate.key < lastKey) lower = middle + 1;
+		else upper = middle - 1;
+	}
+	return invalidArgument$1();
+};
+/** Creates the returned inspection from content-free state only. */
+var createPreparedProjectInspection = (input) => {
+	const { counts, formatVersion, items, maxEntries, maxRetainedBytes, resourceUsage: validationUsage, source, summary, valid } = input;
+	const views = createViews(items);
+	const inspectionDigest = createIdentity([serializeDeterministically({
+		counts,
+		formatVersion,
+		itemKeys: items.map(({ key }) => key),
+		summary,
+		valid
+	})]);
+	const preparedBytes = calculatePreparedBytes(items, views, {
+		counts,
+		formatVersion,
+		inspectionDigest,
+		source,
+		summary,
+		valid
+	}, validationUsage.retainedBytes, maxRetainedBytes);
+	const resourceUsage = freezeRecursively({
+		canonicalBytes: validationUsage.canonicalBytes,
+		peakRetainedBytes: Math.max(validationUsage.peakRetainedBytes, validationUsage.retainedBytes + preparedBytes),
+		preparedBytes,
+		retainedBytes: preparedBytes,
+		totalBytesRead: validationUsage.totalBytesRead
+	});
+	const readPage = (pageInput) => {
+		if (typeof pageInput !== "object" || pageInput === null || Reflect.ownKeys(pageInput).some((key) => key !== "cursor" && key !== "maxItems" && key !== "view") || !Number.isSafeInteger(pageInput.maxItems) || pageInput.maxItems < 1 || pageInput.maxItems > maxEntries || pageInput.cursor !== void 0 && typeof pageInput.cursor !== "string" || pageInput.view !== "all" && pageInput.view !== "diagnostics" && pageInput.view !== "evidence" && pageInput.view !== "metadata") return invalidArgument$1();
+		const viewItems = views[pageInput.view];
+		const startIndex = findStartIndex(viewItems, decodeCursor(pageInput.cursor, inspectionDigest, pageInput.view));
+		const records = viewItems.slice(startIndex, startIndex + pageInput.maxItems).map(({ item, key }, index) => {
+			return {
+				item,
+				nextCursor: startIndex + index + 1 >= viewItems.length ? null : encodeCursor(inspectionDigest, pageInput.view, key)
+			};
+		});
+		const nextCursor = records.at(-1)?.nextCursor ?? null;
+		return freezeRecursively({
+			counts,
+			formatVersion,
+			inspectionDigest,
+			page: {
+				isComplete: nextCursor === null,
+				nextCursor,
+				records,
+				totalItems: viewItems.length
+			},
+			source,
+			summary,
+			valid,
+			view: pageInput.view
+		});
+	};
+	return freezeRecursively({
+		counts,
+		formatVersion,
+		inspectionDigest,
+		readPage,
+		resourceUsage,
+		source,
+		summary,
+		valid
+	});
+};
+/** Prepares one immutable content-free inspection for synchronous bounded page reads. */
+var createProjectInspection = async (input, options) => {
+	const state = await validateProjectState(input, options);
 	const metadata = state.project === null ? [] : collectProjectMetadata(state.project);
 	const agentAssignments = state.project === null ? [] : collectProjectAgentAssignments(state.project);
-	const allItems = createKeyedItems([
+	const items = freezeRecursively(createKeyedItems([
 		...metadata.map((metadataItem) => ({
 			kind: "metadata",
 			metadata: metadataItem
@@ -5005,50 +5169,27 @@ var inspectProjectPage = async (input, options) => {
 			agent,
 			kind: "agent"
 		}))
-	]);
-	const counts = {
-		agents: state.result.summary?.counts.agents ?? 0,
-		context: state.result.summary?.counts.context ?? 0,
-		decisions: state.result.summary?.counts.decisions ?? 0,
-		diagnostics: state.result.diagnostics.length,
-		evidence: state.result.evidence.length,
-		metadata: metadata.length,
-		mirrors: state.result.summary?.counts.mirrors ?? 0,
-		runtimes: state.result.summary?.counts.runtimes ?? 0,
-		unresolved: state.result.summary?.counts.unresolved ?? 0
-	};
-	const inspectionDigest = createIdentity([serializeDeterministically({
-		counts,
-		formatVersion: state.result.formatVersion,
-		itemKeys: allItems.map(({ key }) => key),
-		summary: state.result.summary,
-		valid: state.result.valid
-	})]);
-	const items = selectViewItems(allItems, input.view);
-	const lastKey = decodeCursor(input.cursor, inspectionDigest, input.view);
-	const startIndex = lastKey === null ? 0 : items.findIndex(({ key }) => key === lastKey) + 1;
-	if (lastKey !== null && startIndex === 0) return invalidArgument$1();
-	const records = items.slice(startIndex, startIndex + input.maxItems).map(({ item, key }, index) => {
-		return {
-			item,
-			nextCursor: startIndex + index + 1 >= items.length ? null : encodeCursor(inspectionDigest, input.view, key)
-		};
-	});
-	const nextCursor = records.at(-1)?.nextCursor ?? null;
-	return freezeRecursively({
-		counts,
+	]));
+	return createPreparedProjectInspection({
+		counts: freezeRecursively({
+			agents: state.result.summary?.counts.agents ?? 0,
+			context: state.result.summary?.counts.context ?? 0,
+			decisions: state.result.summary?.counts.decisions ?? 0,
+			diagnostics: state.result.diagnostics.length,
+			evidence: state.result.evidence.length,
+			metadata: metadata.length,
+			mirrors: state.result.summary?.counts.mirrors ?? 0,
+			runtimes: state.result.summary?.counts.runtimes ?? 0,
+			unresolved: state.result.summary?.counts.unresolved ?? 0
+		}),
 		formatVersion: state.result.formatVersion,
-		inspectionDigest,
-		page: {
-			isComplete: nextCursor === null,
-			nextCursor,
-			records,
-			totalItems: items.length
-		},
+		items,
+		maxEntries: options.limits.maxEntries,
+		maxRetainedBytes: options.limits.maxRetainedBytes,
+		resourceUsage: state.resourceUsage,
 		source: state.result.source,
 		summary: state.result.summary,
-		valid: state.result.valid,
-		view: input.view
+		valid: state.result.valid
 	});
 };
 //#endregion
@@ -5064,10 +5205,13 @@ var invalidArgument = () => {
 	});
 };
 /** Throws the stable resource failure for an exhausted scope-input budget. */
-var resourceLimitExceeded = (limit) => {
+var resourceLimitExceeded = (limit, limitMaximum, observedUsage) => {
 	throw new CoreOperationException({
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit,
+		limitMaximum,
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage,
 		operation: "match-manifest-scope"
 	});
 };
@@ -5095,14 +5239,14 @@ var normalizeManifestScopeInput = (input, limits) => {
 	const manifest = input["manifest"];
 	const pathCandidates = input["paths"];
 	if (!isRecord(manifest) || !Array.isArray(pathCandidates)) return invalidArgument();
-	if (pathCandidates.length > limits.maxEntries) return resourceLimitExceeded("maxEntries");
+	if (pathCandidates.length > limits.maxEntries) return resourceLimitExceeded("maxEntries", limits.maxEntries, pathCandidates.length);
 	const uniquePaths = /* @__PURE__ */ new Set();
 	let totalBytes = 0;
 	for (const [index, candidate] of pathCandidates.entries()) {
 		if (typeof candidate !== "string") return invalidArgument();
 		const path = parseRepositoryPath(candidate);
 		totalBytes += measureUtf8ByteLength(path) + (index === 0 ? 0 : 1);
-		if (totalBytes > limits.maxTotalBytesRead) return resourceLimitExceeded("maxTotalBytesRead");
+		if (totalBytes > limits.maxTotalBytesRead) return resourceLimitExceeded("maxTotalBytesRead", limits.maxTotalBytesRead, totalBytes);
 		uniquePaths.add(path);
 	}
 	return {
@@ -5293,6 +5437,9 @@ var compileManifestScope = (manifest, limits) => {
 	if (declarations.length > limits.maxEntries) throw new CoreOperationException({
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit: "maxEntries",
+		limitMaximum: limits.maxEntries,
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage: declarations.length,
 		operation: "match-manifest-scope"
 	});
 	const exact = /* @__PURE__ */ new Map();
@@ -5340,6 +5487,9 @@ var addMatch = (matches, inputPath, relationship, limits) => {
 	if (matches.length >= limits.maxEntries) throw new CoreOperationException({
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit: "maxEntries",
+		limitMaximum: limits.maxEntries,
+		nextAction: "reduce-input-or-increase-limit",
+		observedUsage: matches.length + 1,
 		operation: "match-manifest-scope"
 	});
 	matches.push(createMatch(inputPath, relationship));
@@ -5454,7 +5604,7 @@ var createCore = (options) => {
 		calculateContentDigest: (input) => {
 			return calculateContentDigest(input, createCoreOperationOptionsSnapshot(snapshot).limits);
 		},
-		inspectProjectPage: (input) => inspectProjectPage(input, createCoreOperationOptionsSnapshot(snapshot)),
+		createProjectInspection: (input) => createProjectInspection(input, createCoreOperationOptionsSnapshot(snapshot)),
 		validateProject: (input) => validateProject(input, createCoreOperationOptionsSnapshot(snapshot)),
 		matchManifestScope: (input) => matchManifestScope(input, createCoreOperationOptionsSnapshot(snapshot)),
 		normalizeText: (input) => {