@moldea.ai/core 3.1.0 → 4.0.1

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as CoreOperationException, t as CoreConfigurationException } from "./chunks/exceptions-DWsZTpqs.js";
+import { n as CoreOperationException, r as registerRuntimeAdapterRetainedByteReservation, t as CoreConfigurationException } from "./chunks/exceptions-HS9ofVy2.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)))}`;
 };
 /**
@@ -2301,11 +2312,13 @@ var parseManifestDocument = async (input, options, operation = "parse-manifest")
 };
 //#endregion
 //#region src/project-agent-assignments/index.ts
-/** Collects deterministic content-free agent-to-runtime assignments from a validated project. */
-var collectProjectAgentAssignments = (project) => project.agents.map((agent) => ({
-	agentId: agent.id,
-	runtimeId: agent.declaration.runtime.id
-})).sort((left, right) => compareExactStrings(left.agentId, right.agentId) || compareExactStrings(left.runtimeId, right.runtimeId));
+/** Iterates content-free agent-to-runtime assignments without retaining an intermediate array. */
+var iterateProjectAgentAssignments = function* (project) {
+	for (const agent of project.agents) yield {
+		agentId: agent.id,
+		runtimeId: agent.declaration.runtime.id
+	};
+};
 //#endregion
 //#region src/project-metadata/index.ts
 var createAssetItem = (asset, kind, agentId = null, decisionId = null) => ({
@@ -2318,18 +2331,18 @@ var createAssetItem = (asset, kind, agentId = null, decisionId = null) => ({
 	path: asset.path,
 	scalarLength: asset.scalarLength
 });
-var compareMetadataItems = (left, right) => compareExactStrings(left.path, right.path) || compareExactStrings(left.kind, right.kind) || compareExactStrings(left.agentId ?? "", right.agentId ?? "");
-/** Collects deterministic content-free asset metadata from one validated project. */
-var collectProjectMetadata = (project) => {
-	const items = [createAssetItem(project.manifest.asset, "manifest"), createAssetItem(project.project, "project")];
-	for (const context of project.context) items.push(createAssetItem(context.asset, "context"));
-	for (const { decision } of project.decisions) items.push(createAssetItem(decision.asset, "decision", null, decision.id));
-	for (const runtime of project.runtimes) items.push(createAssetItem(runtime.asset, "runtime-guidance"));
+/** Iterates content-free asset metadata without retaining a second project-sized collection. */
+var iterateProjectMetadata = function* (project) {
+	yield createAssetItem(project.manifest.asset, "manifest");
+	yield createAssetItem(project.project, "project");
+	for (const context of project.context) yield createAssetItem(context.asset, "context");
+	for (const { decision } of project.decisions) yield createAssetItem(decision.asset, "decision", null, decision.id);
+	for (const runtime of project.runtimes) yield createAssetItem(runtime.asset, "runtime-guidance");
 	for (const agent of project.agents) {
-		items.push(createAssetItem(agent.description.asset, "agent-description", agent.id));
-		items.push(createAssetItem(agent.instruction, "agent-instruction", agent.id));
-		if (agent.handoffDescription !== null) items.push(createAssetItem(agent.handoffDescription.asset, "agent-handoff-description", agent.id));
-		for (const mirror of agent.mirrors) items.push({
+		yield createAssetItem(agent.description.asset, "agent-description", agent.id);
+		yield createAssetItem(agent.instruction, "agent-instruction", agent.id);
+		if (agent.handoffDescription !== null) yield createAssetItem(agent.handoffDescription.asset, "agent-handoff-description", agent.id);
+		for (const mirror of agent.mirrors) yield {
 			agentId: agent.id,
 			byteLength: mirror.byteLength,
 			canonicalDigest: mirror.canonicalDigest,
@@ -2338,9 +2351,8 @@ var collectProjectMetadata = (project) => {
 			kind: "mirror",
 			path: mirror.path,
 			scalarLength: mirror.scalarLength
-		});
+		};
 	}
-	return items.sort(compareMetadataItems);
 };
 /** Creates the content-free summary for one validated project snapshot. */
 var createProjectSummary = (project) => ({
@@ -2472,6 +2484,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 +2852,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 +2888,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 +2913,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 +2931,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 +2952,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 +2999,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 +3082,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 +3113,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 {
@@ -3099,8 +3149,15 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 		readFilePage: readAdapterFilePage,
 		snapshot: repository.snapshot
 	});
+	registerRuntimeAdapterRetainedByteReservation(adapterRepository, reserveRetainedBytes);
 	return Object.freeze({
 		adapterRepository,
+		getResourceUsage: () => Object.freeze({
+			canonicalBytes,
+			peakRetainedBytes,
+			retainedBytes,
+			totalBytesRead
+		}),
 		reader: Object.freeze({
 			getEntry,
 			iterateEntries,
@@ -4846,6 +4903,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 +4917,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 +4931,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 +4945,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);
@@ -4903,7 +4977,9 @@ var serializeDeterministically = (candidate) => {
 	if (Array.isArray(candidate)) return `[${candidate.map((item) => serializeDeterministically(item)).join(",")}]`;
 	return `{${Object.entries(candidate).filter(([, value]) => value !== void 0).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0).map(([key, value]) => `${JSON.stringify(key)}:${serializeDeterministically(value)}`).join(",")}}`;
 };
-var createIdentity = (parts) => createRepositoryIdentity(parts.map((part) => encoder.encode(part)));
+var createIdentity = (parts) => createRepositoryIdentity((function* () {
+	for (const part of parts) yield encoder.encode(part);
+})());
 var createItemBaseKey = (item) => {
 	if (item.kind === "agent") return [
 		"3",
@@ -4933,21 +5009,21 @@ 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),
-		item
-	})).sort((left, right) => left.baseKey < right.baseKey ? -1 : left.baseKey > right.baseKey ? 1 : 0);
-	const occurrences = /* @__PURE__ */ new Map();
-	return sorted.map(({ baseKey, item }) => {
-		const occurrence = occurrences.get(baseKey) ?? 0;
-		occurrences.set(baseKey, occurrence + 1);
-		return {
-			item,
-			key: `${baseKey}:${String(occurrence).padStart(10, "0")}`
-		};
-	});
+	const sorted = Array.from(items, (item) => ({
+		item,
+		key: createItemBaseKey(item)
+	})).sort((left, right) => left.key < right.key ? -1 : left.key > right.key ? 1 : 0);
+	let previousBaseKey = null;
+	let occurrence = 0;
+	for (const item of sorted) {
+		const baseKey = item.key;
+		occurrence = baseKey === previousBaseKey ? occurrence + 1 : 0;
+		previousBaseKey = baseKey;
+		item.key = `${baseKey}:${String(occurrence).padStart(10, "0")}`;
+	}
+	return sorted;
 };
 var createCursorChecksum = (inspectionDigest, lastKey, view) => createIdentity([
 	CURSOR_PREFIX,
@@ -4964,7 +5040,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,80 +5051,171 @@ 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);
-	const metadata = state.project === null ? [] : collectProjectMetadata(state.project);
-	const agentAssignments = state.project === null ? [] : collectProjectAgentAssignments(state.project);
-	const allItems = createKeyedItems([
-		...metadata.map((metadataItem) => ({
-			kind: "metadata",
-			metadata: metadataItem
-		})),
-		...state.result.diagnostics.map((diagnostic) => ({
-			diagnostic,
-			kind: "diagnostic"
-		})),
-		...state.result.evidence.map((evidence) => ({
-			evidence,
-			kind: "evidence"
-		})),
-		...agentAssignments.map((agent) => ({
-			agent,
-			kind: "agent"
-		}))
-	]);
+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;
+};
+/** Iterates every content-free inspection item without retaining preparation state. */
+var iterateProjectInspectionItems = function* (state) {
+	if (state.project !== null) for (const metadata of iterateProjectMetadata(state.project)) yield {
+		kind: "metadata",
+		metadata
+	};
+	for (const diagnostic of state.result.diagnostics) yield {
+		diagnostic,
+		kind: "diagnostic"
+	};
+	for (const evidence of state.result.evidence) yield {
+		evidence,
+		kind: "evidence"
+	};
+	if (state.project !== null) for (const agent of iterateProjectAgentAssignments(state.project)) yield {
+		agent,
+		kind: "agent"
+	};
+};
+/** Preflights the complete logical prepared-state cost before retaining its collections. */
+var estimatePreparedProjectInspection = (state, baseCounts, maximum) => {
+	const retainedBeforePreparation = state.resourceUsage.retainedBytes;
+	let bytes = addRetainedBytes(0, PREPARED_FIXED_BYTES, retainedBeforePreparation, maximum);
+	let metadataCount = 0;
+	for (const item of iterateProjectInspectionItems(state)) {
+		const key = `${createItemBaseKey(item)}:0000000000`;
+		const encodedBytes = encoder.encode(key).byteLength + encoder.encode(serializeDeterministically(item)).byteLength;
+		bytes = addRetainedBytes(bytes, PREPARED_ITEM_FIXED_BYTES + encodedBytes * PREPARED_TEXT_BYTE_MULTIPLIER + PREPARED_VIEW_REFERENCE_BYTES, retainedBeforePreparation, maximum);
+		if (item.kind === "metadata") metadataCount += 1;
+	}
 	const counts = {
+		agents: baseCounts.agents,
+		context: baseCounts.context,
+		decisions: baseCounts.decisions,
+		diagnostics: baseCounts.diagnostics,
+		evidence: baseCounts.evidence,
+		metadata: metadataCount,
+		mirrors: baseCounts.mirrors,
+		runtimes: baseCounts.runtimes,
+		unresolved: baseCounts.unresolved
+	};
+	bytes = addRetainedBytes(bytes, encoder.encode(serializeDeterministically({
+		counts,
+		formatVersion: state.result.formatVersion,
+		inspectionDigest: "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+		source: state.result.source,
+		summary: state.result.summary,
+		valid: state.result.valid
+	})).byteLength * PREPARED_TEXT_BYTE_MULTIPLIER, retainedBeforePreparation, maximum);
+	return {
+		counts,
+		preparedBytes: bytes
+	};
+};
+/** Creates the inspection digest without materializing a project-sized key projection. */
+var createInspectionDigest = (counts, formatVersion, items, summary, valid) => createIdentity((function* () {
+	yield "core4-prepared-inspection";
+	yield serializeDeterministically({
+		counts,
+		formatVersion,
+		summary,
+		valid
+	});
+	for (const { key } of items) yield key;
+})());
+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, preparedBytes, resourceUsage: validationUsage, source, summary, valid } = input;
+	const views = createViews(items);
+	const inspectionDigest = createInspectionDigest(counts, formatVersion, items, summary, valid);
+	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 estimate = estimatePreparedProjectInspection(state, {
 		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({
+	}, options.limits.maxRetainedBytes);
+	const counts = freezeRecursively(estimate.counts);
+	const items = freezeRecursively(createKeyedItems(iterateProjectInspectionItems(state)));
+	return createPreparedProjectInspection({
 		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,
-		formatVersion: state.result.formatVersion,
-		inspectionDigest,
-		page: {
-			isComplete: nextCursor === null,
-			nextCursor,
-			records,
-			totalItems: items.length
-		},
+		items,
+		maxEntries: options.limits.maxEntries,
+		preparedBytes: estimate.preparedBytes,
+		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 +5231,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 +5265,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 +5463,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 +5513,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 +5630,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) => {