@moldea.ai/core 2.1.0 → 3.0.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import { REPOSITORY_ROOT, RepositoryPathException, RepositorySourceException, isRepositoryPath, parseRepositoryPath } from "@moldea.ai/repository";
-import { Exception } from "error-message-utils";
+import { n as CoreOperationException, t as CoreConfigurationException } from "./chunks/exceptions-DWsZTpqs.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
 var RECOGNIZED_RUNTIME_ADAPTER_IDS = Object.freeze([
@@ -25,69 +25,154 @@ var DEFAULT_CORE_RESOURCE_LIMITS = Object.freeze({
 	maxTotalBytesRead: 134217728
 });
 //#endregion
-//#region src/exceptions/index.ts
-var CONFIGURATION_ERROR_MESSAGES = {
-	DUPLICATE_ADAPTER_ID: "A runtime adapter ID is registered more than once.",
-	INVALID_ADAPTER_DEFINITION: "A runtime adapter definition is invalid.",
-	INVALID_RESOURCE_LIMIT: "A Core resource limit is invalid.",
-	RESERVED_ADAPTER_ID: "A reserved runtime adapter ID was supplied."
-};
-var OPERATION_ERROR_MESSAGES = {
-	ABORTED: "The Core operation was aborted.",
-	ADAPTER_EXECUTION_FAILED: "A runtime adapter failed during inspection.",
-	INVALID_ARGUMENT: "The Core operation received an invalid argument.",
-	RESOURCE_LIMIT_EXCEEDED: "A Core resource limit was exceeded."
-};
-var OPERATION_ERROR_RETRYABILITY = {
-	ABORTED: true,
-	ADAPTER_EXECUTION_FAILED: false,
-	INVALID_ARGUMENT: false,
-	RESOURCE_LIMIT_EXCEEDED: false
-};
-var attachCause = (exception, cause) => {
-	if (cause === void 0) return;
-	Object.defineProperty(exception, "cause", {
-		configurable: true,
-		enumerable: false,
-		value: cause,
-		writable: false
+//#region src/immutable/index.ts
+/**
+* Recursively freezes a Core-owned value without cloning it.
+* @param value The detached acyclic value whose already-frozen objects are deeply frozen.
+* @returns The same value with every mutable reachable object frozen.
+*/
+var freezeRecursively = (value) => {
+	if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
+	for (const key of Reflect.ownKeys(value)) {
+		const child = value[key];
+		freezeRecursively(child);
+	}
+	return Object.freeze(value);
+};
+/**
+* Creates a record that cannot collide with prototype-chain properties.
+* @param entries The own string-keyed entries to assign.
+* @returns A mutable null-prototype record for later normalization and freezing.
+*/
+var createNullPrototypeRecord = (entries) => {
+	const record = Object.create(null);
+	for (const [key, value] of entries) record[key] = value;
+	return record;
+};
+//#endregion
+//#region src/canonical-content-page/index.ts
+var decoder$1 = new TextDecoder("utf-8", {
+	fatal: true,
+	ignoreBOM: true
+});
+var invalidArgument$4 = () => {
+	throw new CoreOperationException({
+		code: "INVALID_ARGUMENT",
+		operation: "read-canonical-content-page"
 	});
 };
-/** Represents invalid immutable Core configuration. */
-var CoreConfigurationException = class extends Exception {
-	code;
-	operation;
-	adapterId;
-	/** Creates a configuration exception with safe adapter metadata. */
-	constructor(options) {
-		super(CONFIGURATION_ERROR_MESSAGES[options.code], options.code);
-		this.code = options.code;
-		this.name = "CoreConfigurationException";
-		this.operation = options.operation;
-		this.adapterId = options.adapterId ?? null;
-		attachCause(this, options.cause);
-	}
-};
-/** Represents an operational failure that prevented Core from completing. */
-var CoreOperationException = class extends Exception {
-	code;
-	operation;
-	retryable;
-	adapterId;
-	agentId;
-	limit;
-	/** Creates an operation exception with derived retry and safe scope metadata. */
-	constructor(options) {
-		super(OPERATION_ERROR_MESSAGES[options.code], options.code);
-		this.code = options.code;
-		this.name = "CoreOperationException";
-		this.operation = options.operation;
-		this.retryable = OPERATION_ERROR_RETRYABILITY[options.code];
-		this.adapterId = options.adapterId ?? null;
-		this.agentId = options.agentId ?? null;
-		this.limit = options.limit ?? null;
-		attachCause(this, options.cause);
+var invalidContent = () => {
+	throw new CoreOperationException({
+		code: "CONTENT_INVALID",
+		operation: "read-canonical-content-page"
+	});
+};
+var isRepositoryReader$1 = (candidate) => typeof candidate === "object" && candidate !== null && typeof candidate.getEntry === "function" && typeof candidate.readFilePage === "function";
+var readBytes = async (repository, path, offset, maxBytes, signal) => {
+	const chunks = [];
+	let byteLength = 0;
+	let nextOffset = offset;
+	let lastPage = null;
+	let totalBytes = null;
+	while (byteLength < maxBytes) {
+		const page = await repository.readFilePage(path, {
+			maxBytes: maxBytes - byteLength,
+			offset: nextOffset,
+			...signal === void 0 ? {} : { signal }
+		});
+		if (page.snapshot.id !== repository.snapshot.id || page.offset !== nextOffset || page.bytes.byteLength > maxBytes - byteLength || page.totalBytes < page.offset + page.bytes.byteLength || totalBytes !== null && page.totalBytes !== totalBytes || page.bytes.byteLength === 0 && !page.isComplete) throw new RepositorySourceException({
+			code: "INVALID_SOURCE_DATA",
+			operation: "read-file-page",
+			path,
+			retryable: false
+		});
+		chunks.push(page.bytes);
+		byteLength += page.bytes.byteLength;
+		totalBytes = page.totalBytes;
+		lastPage = page;
+		if (page.isComplete || byteLength === maxBytes) break;
+		if (page.nextOffset !== page.offset + page.bytes.byteLength) throw new RepositorySourceException({
+			code: "INVALID_SOURCE_DATA",
+			operation: "read-file-page",
+			path,
+			retryable: false
+		});
+		nextOffset = page.nextOffset;
 	}
+	if (lastPage === null) return invalidArgument$4();
+	const bytes = new Uint8Array(byteLength);
+	let writeOffset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, writeOffset);
+		writeOffset += chunk.byteLength;
+	}
+	return {
+		bytes,
+		lastPage
+	};
+};
+var decodeSafePrefix = (bytes, maximumBytes) => {
+	const minimumCandidate = Math.max(0, maximumBytes - 3);
+	for (let end = maximumBytes; end >= minimumCandidate; end -= 1) try {
+		const content = decoder$1.decode(bytes.subarray(0, end));
+		if (end === 0 && bytes.byteLength > 0) continue;
+		return [content, end];
+	} catch {}
+	return invalidContent();
+};
+/** Reads one explicit canonical file range without materializing the complete file. */
+var readCanonicalContentPage = async (input, options) => {
+	if (typeof input !== "object" || input === null || Reflect.ownKeys(input).some((key) => key !== "maxBytes" && key !== "offset" && key !== "path" && key !== "repository" && key !== "signal") || !isRepositoryReader$1(input.repository) || !Number.isSafeInteger(input.maxBytes) || input.maxBytes < 1 || input.maxBytes > options.limits.maxFileBytes || !Number.isSafeInteger(input.offset) || input.offset < 0) return invalidArgument$4();
+	const path = parseRepositoryPath(input.path);
+	if (!path.startsWith("/moldea/")) return invalidArgument$4();
+	const operationOptions = input.signal === void 0 ? void 0 : { signal: input.signal };
+	const entry = await input.repository.getEntry(path, operationOptions);
+	if (entry === null) throw new RepositorySourceException({
+		code: "ENTRY_NOT_FOUND",
+		operation: "read-file-page",
+		path,
+		retryable: false
+	});
+	if (entry.type !== "file" || entry.byteLength === null) throw new RepositorySourceException({
+		code: "ENTRY_NOT_FILE",
+		operation: "read-file-page",
+		path,
+		retryable: false
+	});
+	if (entry.byteLength > options.limits.maxFileBytes) throw new CoreOperationException({
+		code: "RESOURCE_LIMIT_EXCEEDED",
+		limit: "maxFileBytes",
+		operation: "read-canonical-content-page"
+	});
+	if (input.offset > entry.byteLength) return invalidArgument$4();
+	if (input.offset === entry.byteLength) return freezeRecursively({
+		byteEnd: input.offset,
+		byteStart: input.offset,
+		content: "",
+		contentIdentity: entry.contentIdentity,
+		isComplete: true,
+		nextOffset: null,
+		path,
+		source: input.repository.snapshot,
+		totalBytes: entry.byteLength
+	});
+	const lookaheadBytes = Math.min(entry.byteLength - input.offset, input.maxBytes + 3);
+	const { bytes, lastPage } = await readBytes(input.repository, path, input.offset, lookaheadBytes, input.signal);
+	if (lastPage.totalBytes !== entry.byteLength || (bytes[0] & 192) === 128) return invalidArgument$4();
+	const [content, consumedBytes] = decodeSafePrefix(bytes, Math.min(input.maxBytes, bytes.byteLength));
+	const byteEnd = input.offset + consumedBytes;
+	const isComplete = byteEnd === entry.byteLength;
+	return freezeRecursively({
+		byteEnd,
+		byteStart: input.offset,
+		content,
+		contentIdentity: entry.contentIdentity,
+		isComplete,
+		nextOffset: isComplete ? null : byteEnd,
+		path,
+		source: input.repository.snapshot,
+		totalBytes: entry.byteLength
+	});
 };
 //#endregion
 //#region src/format-validation/index.ts
@@ -248,31 +333,6 @@ var sortRepositoryReferences = (references) => {
 	});
 };
 //#endregion
-//#region src/immutable/index.ts
-/**
-* Recursively freezes a Core-owned value without cloning it.
-* @param value The detached acyclic value whose already-frozen objects are deeply frozen.
-* @returns The same value with every mutable reachable object frozen.
-*/
-var freezeRecursively = (value) => {
-	if (typeof value !== "object" || value === null || Object.isFrozen(value)) return value;
-	for (const key of Reflect.ownKeys(value)) {
-		const child = value[key];
-		freezeRecursively(child);
-	}
-	return Object.freeze(value);
-};
-/**
-* Creates a record that cannot collide with prototype-chain properties.
-* @param entries The own string-keyed entries to assign.
-* @returns A mutable null-prototype record for later normalization and freezing.
-*/
-var createNullPrototypeRecord = (entries) => {
-	const record = Object.create(null);
-	for (const [key, value] of entries) record[key] = value;
-	return record;
-};
-//#endregion
 //#region src/diagnostic-utilities/index.ts
 var CORE_DIAGNOSTIC_MESSAGES = {
 	MOLDEA_AGENT_DESCRIPTION_INVALID: "The agent description is invalid.",
@@ -904,7 +964,7 @@ var createSourceLocator = (value) => {
 };
 //#endregion
 //#region src/text/index.ts
-var encoder = new TextEncoder();
+var encoder$1 = new TextEncoder();
 var decoder = new TextDecoder("utf-8", {
 	fatal: true,
 	ignoreBOM: true
@@ -982,7 +1042,7 @@ var collectNulDiagnostics = (value, path, diagnostics) => {
 		offset += 1;
 	}
 };
-var invalidArgument$2 = (operation) => {
+var invalidArgument$3 = (operation) => {
 	throw new CoreOperationException({
 		code: "INVALID_ARGUMENT",
 		operation
@@ -1017,10 +1077,10 @@ var invalidResult = (diagnostics) => {
 * - RESOURCE_LIMIT_EXCEEDED: A Core resource limit was exceeded.
 */
 var readInput = (input, limits, operation, limit, diagnostics) => {
-	if (!isRecord$3(input)) return invalidArgument$2(operation);
+	if (!isRecord$3(input)) return invalidArgument$3(operation);
 	const pathCandidate = input["path"];
 	const content = input["content"];
-	if (typeof pathCandidate !== "string" || typeof content !== "string" && !(content instanceof Uint8Array)) return invalidArgument$2(operation);
+	if (typeof pathCandidate !== "string" || typeof content !== "string" && !(content instanceof Uint8Array)) return invalidArgument$3(operation);
 	const path = parseRepositoryPath(pathCandidate);
 	if (typeof content === "string") {
 		const byteLength = measureScalarUtf8ByteLength(content, limits[limit]);
@@ -1075,7 +1135,7 @@ var normalizeTextDocument = (input, limits, operation, limit = "maxFileBytes") =
 		diagnostics: [],
 		text: freezeRecursively({
 			scalarLength: countUnicodeScalars(value),
-			utf8ByteLength: encoder.encode(value).byteLength,
+			utf8ByteLength: encoder$1.encode(value).byteLength,
 			value
 		}),
 		valid: true
@@ -1092,7 +1152,7 @@ var toLowercaseHex = (bytes) => {
 * @returns A promise resolving to the canonical lowercase SHA-256 digest.
 */
 var calculateNormalizedTextDigest = async (text) => {
-	const bytes = encoder.encode(text.value);
+	const bytes = encoder$1.encode(text.value);
 	return `sha256:${toLowercaseHex(new Uint8Array(await globalThis.crypto.subtle.digest("SHA-256", bytes)))}`;
 };
 /**
@@ -2240,6 +2300,57 @@ var parseManifestDocument = async (input, options, operation = "parse-manifest")
 	});
 };
 //#endregion
+//#region src/project-metadata/index.ts
+var createAssetItem = (asset, kind, agentId = null, decisionId = null) => ({
+	agentId,
+	byteLength: asset.utf8ByteLength,
+	canonicalDigest: null,
+	decisionId,
+	digest: asset.digest,
+	kind,
+	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"));
+	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({
+			agentId: agent.id,
+			byteLength: mirror.byteLength,
+			canonicalDigest: mirror.canonicalDigest,
+			decisionId: null,
+			digest: mirror.digest,
+			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) => ({
+	counts: {
+		agents: project.agents.length,
+		context: project.context.length,
+		decisions: project.decisions.length,
+		mirrors: project.agents.reduce((count, agent) => count + agent.mirrors.length, 0),
+		runtimes: project.runtimes.length,
+		unresolved: Object.keys(project.unresolved).length
+	},
+	manifestDigest: project.manifest.asset.digest,
+	manifestPath: project.manifest.asset.path,
+	projectDigest: project.project.digest,
+	projectPath: project.project.path
+});
+//#endregion
 //#region src/adapter-availability/index.ts
 /**
 * Validates adapter availability and format support before any runtime adapter runs.
@@ -2251,7 +2362,7 @@ var parseManifestDocument = async (input, options, operation = "parse-manifest")
 * - RESOURCE_LIMIT_EXCEEDED: The raw Core diagnostic limit was exceeded.
 */
 var validateRuntimeAdapterAvailability = (locations, formatVersion, options) => {
-	const diagnostics = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const diagnostics = createCoreDiagnosticCollector(options.limits, "validate-project");
 	const adapters = new Map(options.adapters.map((adapter) => [adapter.id, adapter]));
 	for (const location of locations) {
 		if (location.adapterId === "custom") continue;
@@ -2589,18 +2700,58 @@ var validateRuntimeAdapterResult = async (candidate, context, outputCounts) => {
 //#endregion
 //#region src/adapter-execution/index.ts
 var isInspectionBoundaryFailure = (error) => {
-	return error instanceof RepositoryPathException || error instanceof RepositorySourceException || error instanceof CoreOperationException && error.operation === "inspect-project" && (error.code === "ABORTED" || error.code === "RESOURCE_LIMIT_EXCEEDED");
-};
-var invokeAdapter = async (adapter, project, session, options, outputCounts, signal) => {
-	const agents = freezeRecursively(project.agents.filter(({ declaration }) => declaration.runtime.id === adapter.id));
-	if (agents.length === 0) return freezeRecursively({
-		diagnostics: [],
-		evidence: []
-	});
+	return error instanceof RepositoryPathException || error instanceof RepositorySourceException || error instanceof CoreOperationException && error.operation === "validate-project" && (error.code === "ABORTED" || error.code === "RESOURCE_LIMIT_EXCEEDED");
+};
+var getRuntimeBindingKey = (reference) => JSON.stringify([reference.path, reference.symbol ?? null]);
+/** Builds one compact exact-binding index for a single configured runtime. */
+var createRuntimeAgentBindingIndex = (agents) => {
+	const candidates = /* @__PURE__ */ new Map();
+	for (const agent of agents) {
+		const runtimeAgent = agent.declaration.bindings?.runtimeAgent;
+		if (runtimeAgent === void 0) continue;
+		const key = getRuntimeBindingKey(runtimeAgent);
+		const existing = candidates.get(key);
+		if (existing !== void 0) {
+			candidates.set(key, {
+				candidateCount: existing.kind === "matched" ? 2 : existing.candidateCount + 1,
+				kind: "ambiguous"
+			});
+			continue;
+		}
+		candidates.set(key, {
+			agent,
+			kind: "matched",
+			resolved: freezeRecursively({
+				declaration: agent.declaration,
+				description: agent.description,
+				handoffDescription: agent.handoffDescription,
+				id: agent.id
+			})
+		});
+	}
+	return candidates;
+};
+var invokeAdapter = async (adapter, agent, agentBindings, project, session, options, outputCounts, signal) => {
+	const scopedAgent = freezeRecursively(agent);
+	const resolvedAgents = /* @__PURE__ */ new Map([[scopedAgent.id, scopedAgent]]);
+	const repository = session.adapterRepository;
+	const resolveAgent = (reference) => {
+		const resolution = agentBindings.get(getRuntimeBindingKey(reference));
+		if (resolution === void 0) return Object.freeze({ kind: "absent" });
+		if (resolution.kind === "ambiguous") return Object.freeze({
+			candidateCount: resolution.candidateCount,
+			kind: "ambiguous"
+		});
+		resolvedAgents.set(resolution.agent.id, resolution.agent);
+		return Object.freeze({
+			agent: resolution.resolved,
+			kind: "matched"
+		});
+	};
 	const context = Object.freeze({
-		agents,
-		project,
-		repository: session.reader,
+		agent: scopedAgent,
+		repository,
+		resolveAgent,
 		...signal === void 0 ? {} : { signal }
 	});
 	let candidate;
@@ -2615,15 +2766,15 @@ var invokeAdapter = async (adapter, project, session, options, outputCounts, sig
 			adapterId: adapter.id,
 			cause: error,
 			code: "ADAPTER_EXECUTION_FAILED",
-			operation: "inspect-project"
+			operation: "validate-project"
 		});
 	}
 	return validateRuntimeAdapterResult(candidate, {
 		adapterId: adapter.id,
-		agents,
+		agents: [...resolvedAgents.values()],
 		limits: options.limits,
 		project,
-		repository: session.reader,
+		repository: session.adapterRepository,
 		...signal === void 0 ? {} : { signal }
 	}, outputCounts);
 };
@@ -2654,10 +2805,20 @@ var inspectRuntimeAdapters = async (project, session, options, signal) => {
 		diagnostics: 0,
 		evidence: 0
 	};
+	const agentsByRuntimeId = /* @__PURE__ */ new Map();
+	for (const agent of project.agents) {
+		const runtimeAgents = agentsByRuntimeId.get(agent.declaration.runtime.id);
+		if (runtimeAgents === void 0) agentsByRuntimeId.set(agent.declaration.runtime.id, [agent]);
+		else runtimeAgents.push(agent);
+	}
 	for (const adapter of options.adapters) {
-		const result = await invokeAdapter(adapter, project, session, options, outputCounts, signal);
-		evidence.push(...result.evidence);
-		diagnostics.push(...result.diagnostics);
+		const agents = agentsByRuntimeId.get(adapter.id) ?? [];
+		const agentBindings = createRuntimeAgentBindingIndex(agents);
+		for (const agent of agents) {
+			const result = await invokeAdapter(adapter, agent, agentBindings, project, session, options, outputCounts, signal);
+			evidence.push(...result.evidence);
+			diagnostics.push(...result.diagnostics);
+		}
 	}
 	return freezeRecursively({
 		diagnostics: normalizeDiagnostics(diagnostics),
@@ -2667,6 +2828,8 @@ var inspectRuntimeAdapters = async (project, session, options, signal) => {
 //#endregion
 //#region src/repository-inspection-session/index.ts
 var MANIFEST_PATH$3 = parseRepositoryPath("/moldea/moldea.yaml");
+var SOURCE_PAGE_ENTRIES = 256;
+var SOURCE_PAGE_BYTES = 65536;
 var invalidSourceData$3 = (operation, path) => {
 	throw new RepositorySourceException({
 		code: "INVALID_SOURCE_DATA",
@@ -2680,11 +2843,16 @@ var copyReaderEntry$1 = (candidate, operation, fallbackPath, expectedPath) => {
 	const record = candidate;
 	const pathCandidate = record["path"];
 	const typeCandidate = record["type"];
+	const byteLength = record["byteLength"];
+	const contentIdentity = record["contentIdentity"];
 	if (typeof pathCandidate !== "string" || !isRepositoryPath(pathCandidate)) return invalidSourceData$3(operation, fallbackPath);
 	const path = parseRepositoryPath(pathCandidate);
 	if (expectedPath !== void 0 && path !== expectedPath) return invalidSourceData$3(operation, path);
 	if (typeCandidate !== "file" && typeCandidate !== "directory" && typeCandidate !== "symlink") return invalidSourceData$3(operation, path);
+	if (typeCandidate === "file" ? !Number.isSafeInteger(byteLength) || byteLength < 0 || contentIdentity !== null && typeof contentIdentity !== "string" : byteLength !== null || contentIdentity !== null) return invalidSourceData$3(operation, path);
 	return {
+		byteLength,
+		contentIdentity,
 		path,
 		type: typeCandidate
 	};
@@ -2698,11 +2866,11 @@ var throwResourceLimitExceeded = (limit) => {
 	throw new CoreOperationException({
 		code: "RESOURCE_LIMIT_EXCEEDED",
 		limit,
-		operation: "inspect-project"
+		operation: "validate-project"
 	});
 };
 var createSourceOptions = (sessionSignal, operationSignal) => {
-	const signal = sessionSignal ?? operationSignal;
+	const signal = sessionSignal === void 0 ? operationSignal : operationSignal === void 0 || operationSignal === sessionSignal ? sessionSignal : AbortSignal.any([sessionSignal, operationSignal]);
 	return signal === void 0 ? void 0 : { signal };
 };
 /**
@@ -2710,19 +2878,25 @@ var createSourceOptions = (sessionSignal, operationSignal) => {
 * @param repository The source-neutral reader bound to one coherent snapshot.
 * @param limits The immutable resource limits for the inspection.
 * @param signal Optional cancellation shared by every inspection operation.
-* @returns A frozen session whose reader owns inspection-local budgets and byte caching.
+* @returns A session that pages source metadata and range-reads bounded canonical files.
 * @throws
 * - ABORTED: Repository inspection was aborted before the session was created.
 */
 var createRepositoryInspectionSession = (repository, limits, signal) => {
-	const readCache = /* @__PURE__ */ new Map();
 	const seenPaths = /* @__PURE__ */ new Set();
 	let totalBytesRead = 0;
+	const adapterLimits = Object.freeze({
+		maxEntries: limits.maxEntries,
+		maxFileBytes: limits.maxFileBytes,
+		maxPageBytes: Math.min(SOURCE_PAGE_BYTES, limits.maxFileBytes),
+		maxPageEntries: Math.min(SOURCE_PAGE_ENTRIES, limits.maxEntries),
+		maxTotalBytesRead: limits.maxTotalBytesRead
+	});
 	const createAbortedException = (abortedSignal) => {
 		return new CoreOperationException({
 			cause: abortedSignal.reason,
 			code: "ABORTED",
-			operation: "inspect-project"
+			operation: "validate-project"
 		});
 	};
 	const registerPath = (path) => {
@@ -2732,10 +2906,13 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 	};
 	const throwIfSignalAborted = (operationSignal) => {
 		const abortedSignal = signal?.aborted ? signal : operationSignal?.aborted ? operationSignal : null;
-		if (abortedSignal === null) return;
-		throw createAbortedException(abortedSignal);
+		if (abortedSignal !== null) throw createAbortedException(abortedSignal);
 	};
 	throwIfSignalAborted();
+	const reserveReadBytes = (byteLength) => {
+		if (byteLength > limits.maxTotalBytesRead - totalBytesRead) return throwResourceLimitExceeded("maxTotalBytesRead");
+		totalBytesRead += byteLength;
+	};
 	const getEntry = async (path, options) => {
 		const parsedPath = parseRepositoryPath(path);
 		throwIfSignalAborted(options?.signal);
@@ -2744,82 +2921,184 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 		throwIfSignalAborted(options?.signal);
 		return candidate === null ? null : copyReaderEntry$1(candidate, "get-entry", parsedPath, parsedPath);
 	};
-	const listEntries = (options) => {
+	const iterateEntries = (options) => {
 		const prefix = options?.prefix === void 0 ? REPOSITORY_ROOT : parseRepositoryPath(options.prefix);
 		return { async *[Symbol.asyncIterator]() {
-			throwIfSignalAborted(options?.signal);
 			registerPath(prefix);
 			const yieldedPaths = /* @__PURE__ */ new Set();
-			const sourceOptions = createSourceOptions(signal, options?.signal);
-			const sourceListOptions = sourceOptions === void 0 ? { prefix } : {
-				prefix,
-				...sourceOptions
-			};
-			for await (const candidate of repository.listEntries(sourceListOptions)) {
+			let cursor;
+			let previousPath = null;
+			do {
 				throwIfSignalAborted(options?.signal);
-				const entry = copyReaderEntry$1(candidate, "list-entries", prefix);
-				if (!isStrictDescendant(entry.path, prefix) || yieldedPaths.has(entry.path)) return invalidSourceData$3("list-entries", entry.path);
-				yieldedPaths.add(entry.path);
-				registerPath(entry.path);
-				yield entry;
-			}
-			throwIfSignalAborted(options?.signal);
+				const page = await repository.listEntriesPage({
+					...cursor === void 0 ? {} : { cursor },
+					maxEntries: Math.min(SOURCE_PAGE_ENTRIES, limits.maxEntries),
+					prefix,
+					...createSourceOptions(signal, options?.signal) ?? {}
+				});
+				if (page.snapshot.id !== repository.snapshot.id || page.entries.length === 0 && !page.isComplete) return invalidSourceData$3("list-entries-page", prefix);
+				for (const candidate of page.entries) {
+					throwIfSignalAborted(options?.signal);
+					const entry = copyReaderEntry$1(candidate, "list-entries-page", prefix);
+					if (!isStrictDescendant(entry.path, prefix) || yieldedPaths.has(entry.path) || previousPath !== null && compareRepositoryPaths(previousPath, entry.path) >= 0) return invalidSourceData$3("list-entries-page", entry.path);
+					yieldedPaths.add(entry.path);
+					previousPath = entry.path;
+					registerPath(entry.path);
+					yield entry;
+				}
+				if (page.isComplete) {
+					if (page.nextCursor !== null) return invalidSourceData$3("list-entries-page", prefix);
+					return;
+				}
+				if (page.nextCursor === null || page.nextCursor === cursor) return invalidSourceData$3("list-entries-page", prefix);
+				cursor = page.nextCursor;
+			} while (true);
 		} };
 	};
-	const loadFile = async (path) => {
-		const content = await repository.readFile(path, createSourceOptions(signal, void 0));
-		throwIfSignalAborted();
-		if (!(content instanceof Uint8Array)) return invalidSourceData$3("read-file", path);
+	const loadFile = async (path, operationSignal) => {
 		const fileLimit = path === MANIFEST_PATH$3 ? "maxManifestBytes" : "maxFileBytes";
-		if (content.byteLength > limits[fileLimit]) return throwResourceLimitExceeded(fileLimit);
-		if (totalBytesRead + content.byteLength > limits.maxTotalBytesRead) return throwResourceLimitExceeded("maxTotalBytesRead");
-		totalBytesRead += content.byteLength;
-		return new Uint8Array(content);
-	};
-	const removeFailedRead = async (path, readPromise) => {
-		try {
-			return await readPromise;
-		} catch (error) {
-			readCache.delete(path);
-			throw error;
+		const firstPage = await repository.readFilePage(path, {
+			maxBytes: Math.min(SOURCE_PAGE_BYTES, Math.max(1, limits[fileLimit])),
+			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);
+		reserveReadBytes(firstPage.totalBytes);
+		const content = new Uint8Array(firstPage.totalBytes);
+		let offset = 0;
+		let page = firstPage;
+		let isFirstPage = true;
+		while (isFirstPage || offset < content.byteLength) {
+			isFirstPage = false;
+			if (page.snapshot.id !== repository.snapshot.id || page.offset !== offset || page.totalBytes !== content.byteLength || !(page.bytes instanceof Uint8Array) || page.bytes.byteLength > SOURCE_PAGE_BYTES || page.bytes.byteLength > content.byteLength - offset || page.bytes.byteLength === 0 && !page.isComplete) return invalidSourceData$3("read-file-page", path);
+			content.set(page.bytes, offset);
+			offset += page.bytes.byteLength;
+			if (page.isComplete) {
+				if (page.nextOffset !== null || offset !== content.byteLength) return invalidSourceData$3("read-file-page", path);
+				break;
+			}
+			if (page.nextOffset !== offset) return invalidSourceData$3("read-file-page", path);
+			page = await repository.readFilePage(path, {
+				maxBytes: Math.min(SOURCE_PAGE_BYTES, Math.max(1, content.byteLength - offset)),
+				offset,
+				...createSourceOptions(signal, operationSignal) ?? {}
+			});
+			throwIfSignalAborted(operationSignal);
 		}
+		return content;
 	};
-	const waitForRead = (readPromise, operationSignal) => {
-		throwIfSignalAborted(operationSignal);
-		if (operationSignal === void 0 || operationSignal === signal) return readPromise;
-		let handleAbort;
-		const cancellationPromise = new Promise((resolve, reject) => {
-			handleAbort = () => {
-				const abortedSignal = signal?.aborted ? signal : operationSignal;
-				reject(createAbortedException(abortedSignal));
+	const awaitWithCancellation = async (promise, operationSignal) => {
+		const callerSignal = createSourceOptions(signal, operationSignal)?.signal;
+		if (callerSignal === void 0) return promise;
+		if (callerSignal.aborted) throw createAbortedException(callerSignal);
+		return new Promise((resolve, reject) => {
+			const cleanup = () => callerSignal.removeEventListener("abort", abort);
+			const abort = () => {
+				cleanup();
+				reject(createAbortedException(callerSignal));
 			};
-			operationSignal.addEventListener("abort", handleAbort, { once: true });
-			if (operationSignal.aborted) handleAbort();
-		});
-		return Promise.race([readPromise, cancellationPromise]).finally(() => {
-			operationSignal.removeEventListener("abort", handleAbort);
+			callerSignal.addEventListener("abort", abort, { once: true });
+			promise.then((result) => {
+				cleanup();
+				resolve(result);
+			}, (error) => {
+				cleanup();
+				reject(error instanceof Error ? error : new RepositorySourceException({
+					cause: error,
+					code: "INVALID_SOURCE_DATA",
+					operation: "read-file-page",
+					path: null,
+					retryable: false
+				}));
+			});
 		});
 	};
-	const readFile = async (path, options) => {
+	const readCompleteFile = async (path, options) => {
 		const parsedPath = parseRepositoryPath(path);
 		throwIfSignalAborted(options?.signal);
 		registerPath(parsedPath);
-		let readPromise = readCache.get(parsedPath);
-		if (readPromise === void 0) {
-			readPromise = removeFailedRead(parsedPath, loadFile(parsedPath));
-			readCache.set(parsedPath, readPromise);
-		}
-		const content = await waitForRead(readPromise, options?.signal);
+		const content = await awaitWithCancellation(loadFile(parsedPath, options?.signal), options?.signal);
 		throwIfSignalAborted(options?.signal);
-		return new Uint8Array(content);
+		return content.slice();
+	};
+	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");
+		throwIfSignalAborted(options.signal);
+		const page = await repository.listEntriesPage({
+			...options.cursor === void 0 ? {} : { cursor: options.cursor },
+			maxEntries: options.maxEntries,
+			prefix,
+			...createSourceOptions(signal, options.signal) ?? {}
+		});
+		throwIfSignalAborted(options.signal);
+		if (page.snapshot.id !== repository.snapshot.id || page.entries.length > options.maxEntries || page.entries.length === 0 && !page.isComplete || (page.isComplete ? page.nextCursor !== null : page.nextCursor === null)) return invalidSourceData$3("list-entries-page", prefix);
+		let previousPath = null;
+		const entries = page.entries.map((candidate) => {
+			const entry = copyReaderEntry$1(candidate, "list-entries-page", prefix);
+			if (!isStrictDescendant(entry.path, prefix) || previousPath !== null && compareRepositoryPaths(previousPath, entry.path) >= 0) return invalidSourceData$3("list-entries-page", entry.path);
+			previousPath = entry.path;
+			registerPath(entry.path);
+			return entry;
+		});
+		return Object.freeze({
+			entries: Object.freeze(entries),
+			isComplete: page.isComplete,
+			nextCursor: page.nextCursor,
+			snapshot: repository.snapshot
+		});
+	};
+	const readAdapterFilePage = async (path, options) => {
+		const parsedPath = parseRepositoryPath(path);
+		if (!Number.isSafeInteger(options.offset) || options.offset < 0 || !Number.isSafeInteger(options.maxBytes) || options.maxBytes < 1 || options.maxBytes > adapterLimits.maxPageBytes) return invalidSourceData$3("read-file-page", parsedPath);
+		throwIfSignalAborted(options.signal);
+		registerPath(parsedPath);
+		const reservedBytes = Math.min(options.maxBytes, limits.maxTotalBytesRead - totalBytesRead);
+		if (reservedBytes < 1) return throwResourceLimitExceeded("maxTotalBytesRead");
+		reserveReadBytes(reservedBytes);
+		let page;
+		try {
+			page = await repository.readFilePage(parsedPath, {
+				maxBytes: reservedBytes,
+				offset: options.offset,
+				...createSourceOptions(signal, options.signal) ?? {}
+			});
+		} catch (error) {
+			totalBytesRead -= reservedBytes;
+			throw error;
+		}
+		throwIfSignalAborted(options.signal);
+		if (page.snapshot.id !== repository.snapshot.id || page.offset !== options.offset || !(page.bytes instanceof Uint8Array) || !Number.isSafeInteger(page.totalBytes) || page.totalBytes < 0 || page.totalBytes > limits.maxFileBytes || page.bytes.byteLength > reservedBytes || page.bytes.byteLength > page.totalBytes - page.offset || page.bytes.byteLength === 0 && !page.isComplete || (page.isComplete ? page.nextOffset !== null || page.offset + page.bytes.byteLength !== page.totalBytes : page.nextOffset !== page.offset + page.bytes.byteLength)) {
+			totalBytesRead -= reservedBytes;
+			return invalidSourceData$3("read-file-page", parsedPath);
+		}
+		totalBytesRead -= reservedBytes - page.bytes.byteLength;
+		return Object.freeze({
+			bytes: page.bytes.slice(),
+			isComplete: page.isComplete,
+			nextOffset: page.nextOffset,
+			offset: page.offset,
+			snapshot: repository.snapshot,
+			totalBytes: page.totalBytes
+		});
 	};
-	const reader = Object.freeze({
+	const adapterRepository = Object.freeze({
 		getEntry,
-		listEntries,
-		readFile
+		limits: adapterLimits,
+		listEntriesPage: listAdapterEntriesPage,
+		readFilePage: readAdapterFilePage,
+		snapshot: repository.snapshot
 	});
 	return Object.freeze({
-		reader,
+		adapterRepository,
+		reader: Object.freeze({
+			getEntry,
+			iterateEntries,
+			readCompleteFile
+		}),
 		throwIfAborted: throwIfSignalAborted
 	});
 };
@@ -2845,7 +3124,7 @@ var findNonblankLine = (lines, startIndex) => {
 * - RESOURCE_LIMIT_EXCEEDED: The repository-level diagnostic budget was exceeded.
 */
 var validateAgentDescription = (asset, agentId, kind, limits) => {
-	const diagnostics = createCoreDiagnosticCollector(limits, "inspect-project");
+	const diagnostics = createCoreDiagnosticCollector(limits, "validate-project");
 	const value = trimRepositoryFormatWhitespace(asset.content);
 	const scalarLength = countUnicodeScalars$1(value);
 	const code = kind === "description" ? "MOLDEA_AGENT_DESCRIPTION_INVALID" : "MOLDEA_AGENT_HANDOFF_DESCRIPTION_INVALID";
@@ -2888,7 +3167,7 @@ var validateAgentDescription = (asset, agentId, kind, limits) => {
 * - RESOURCE_LIMIT_EXCEEDED: The repository-level diagnostic budget was exceeded.
 */
 var validateAgentInstruction = (asset, agentId, limits) => {
-	const diagnostics = createCoreDiagnosticCollector(limits, "inspect-project");
+	const diagnostics = createCoreDiagnosticCollector(limits, "validate-project");
 	if (!hasNonWhitespace(asset.content)) {
 		diagnostics.add({
 			code: "MOLDEA_AGENT_INSTRUCTION_EMPTY",
@@ -2924,7 +3203,7 @@ var validateAgentInstruction = (asset, agentId, limits) => {
 var invalidSourceData$2 = (path) => {
 	throw new RepositorySourceException({
 		code: "INVALID_SOURCE_DATA",
-		operation: "read-file",
+		operation: "read-file-page",
 		path,
 		retryable: false
 	});
@@ -2947,12 +3226,12 @@ var invalidSourceData$2 = (path) => {
 * - ABORTED: Repository inspection or the repository read was aborted.
 */
 var readRepositoryTextAsset = async (repository, path, limits, signal) => {
-	const content = await repository.readFile(path, signal === void 0 ? void 0 : { signal });
+	const content = await repository.readCompleteFile(path, signal === void 0 ? void 0 : { signal });
 	if (!(content instanceof Uint8Array)) return invalidSourceData$2(path);
 	const normalized = normalizeTextDocument({
 		content,
 		path
-	}, limits, "inspect-project");
+	}, limits, "validate-project");
 	if (!normalized.valid || normalized.text === null) return freezeRecursively({
 		asset: null,
 		diagnostics: normalized.diagnostics,
@@ -3025,7 +3304,7 @@ var recordOccurrence = (occurrences, variableId, range) => {
 * - RESOURCE_LIMIT_EXCEEDED: The repository-level diagnostic budget was exceeded.
 */
 var validateRuntimePlaceholders = (manifestPath, agentId, instruction, declaredVariables, limits) => {
-	const collector = createCoreDiagnosticCollector(limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(limits, "validate-project");
 	const locator = createSourceLocator(instruction.content);
 	const occurrences = /* @__PURE__ */ new Map();
 	let cursor = 0;
@@ -3182,7 +3461,7 @@ var readInstruction = async (repository, path, agentId, declaration, options, co
 */
 var inspectAgentAssets = async (repository, manifest, discovery, options, signal) => {
 	options = createCoreOperationOptionsSnapshot(options);
-	const collector = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(options.limits, "validate-project");
 	const agents = [];
 	const registeredAgents = manifest.agents ?? {};
 	const registeredIds = new Set(Object.keys(registeredAgents));
@@ -3354,11 +3633,16 @@ var copyReaderEntry = (candidate, operation, expectedPath) => {
 	const record = candidate;
 	const pathCandidate = record["path"];
 	const typeCandidate = record["type"];
+	const byteLength = record["byteLength"];
+	const contentIdentity = record["contentIdentity"];
 	if (typeof pathCandidate !== "string" || !isRepositoryPath(pathCandidate)) return invalidSourceData$1(operation, expectedPath ?? null);
 	const path = parseRepositoryPath(pathCandidate);
 	if (expectedPath !== void 0 && path !== expectedPath) return invalidSourceData$1(operation, path);
 	if (typeCandidate !== "file" && typeCandidate !== "directory" && typeCandidate !== "symlink") return invalidSourceData$1(operation, path);
+	if (typeCandidate === "file" ? !Number.isSafeInteger(byteLength) || byteLength < 0 || contentIdentity !== null && typeof contentIdentity !== "string" : byteLength !== null || contentIdentity !== null) return invalidSourceData$1(operation, path);
 	return {
+		byteLength,
+		contentIdentity,
 		path,
 		type: typeCandidate
 	};
@@ -3408,7 +3692,7 @@ var retainCanonicalFile = (inventory, path, fileKind, agentId) => {
 			inventory.runtimeGuidance.add(path);
 			return;
 	}
-	if (agentId === null) return invalidSourceData$1("list-entries", path);
+	if (agentId === null) return invalidSourceData$1("list-entries-page", path);
 	const agent = getAgent(inventory.agents, agentId);
 	if (fileKind === "agent-description") agent.description = path;
 	else if (fileKind === "agent-instruction") agent.instruction = path;
@@ -3458,7 +3742,7 @@ var retainFoundationEntry = (entry, expectedPath, missingCode, working, diagnost
 	addEntryTypeDiagnostic(diagnostics, entry, "file");
 };
 var checkFoundationListing = (listedEntry, exactEntry) => {
-	if (exactEntry === null || exactEntry.type !== listedEntry.type) return invalidSourceData$1("list-entries", listedEntry.path);
+	if (exactEntry === null || exactEntry.type !== listedEntry.type) return invalidSourceData$1("list-entries-page", listedEntry.path);
 };
 /**
 * Discovers and classifies version 1 canonical assets through one repository snapshot.
@@ -3478,7 +3762,7 @@ var checkFoundationListing = (listedEntry, exactEntry) => {
 * - ABORTED: Discovery or a repository operation was aborted.
 */
 var discoverCanonicalAssets = async (repository, limits, signal, foundations) => {
-	const diagnostics = createCoreDiagnosticCollector(limits, "inspect-project");
+	const diagnostics = createCoreDiagnosticCollector(limits, "validate-project");
 	const working = createWorkingInventory();
 	const moldeaEntry = foundations === void 0 ? await readExactEntry(repository, MOLDEA_ROOT$1, signal) : foundations.moldeaRoot;
 	if (moldeaEntry === null) {
@@ -3507,10 +3791,10 @@ var discoverCanonicalAssets = async (repository, limits, signal, foundations) =>
 		prefix: MOLDEA_ROOT$1,
 		signal
 	};
-	for await (const candidate of repository.listEntries(listOptions)) {
-		const entry = copyReaderEntry(candidate, "list-entries");
-		if (!entry.path.startsWith("/moldea/")) return invalidSourceData$1("list-entries", entry.path);
-		if (seenPaths.has(entry.path)) return invalidSourceData$1("list-entries", entry.path);
+	for await (const candidate of repository.iterateEntries(listOptions)) {
+		const entry = copyReaderEntry(candidate, "list-entries-page");
+		if (!entry.path.startsWith("/moldea/")) return invalidSourceData$1("list-entries-page", entry.path);
+		if (seenPaths.has(entry.path)) return invalidSourceData$1("list-entries-page", entry.path);
 		seenPaths.add(entry.path);
 		if (entry.path === MANIFEST_PATH$1) {
 			checkFoundationListing(entry, manifestEntry);
@@ -3546,8 +3830,8 @@ var discoverCanonicalAssets = async (repository, limits, signal, foundations) =>
 			});
 		}
 	}
-	if (manifestEntry !== null !== listedManifest) return invalidSourceData$1("list-entries", MANIFEST_PATH$1);
-	if (projectEntry !== null !== listedProject) return invalidSourceData$1("list-entries", PROJECT_PATH$1);
+	if (manifestEntry !== null !== listedManifest) return invalidSourceData$1("list-entries-page", MANIFEST_PATH$1);
+	if (projectEntry !== null !== listedProject) return invalidSourceData$1("list-entries-page", PROJECT_PATH$1);
 	return finalizeResult(working, diagnostics);
 };
 //#endregion
@@ -3732,7 +4016,7 @@ var collectCycleDiagnostics = (index, diagnostics) => {
 * - RESOURCE_LIMIT_EXCEEDED: The repository-level diagnostic budget was exceeded.
 */
 var validateDecisionGraph = (candidates, limits) => {
-	const diagnostics = createCoreDiagnosticCollector(limits, "inspect-project");
+	const diagnostics = createCoreDiagnosticCollector(limits, "validate-project");
 	const index = buildGraphIndex(candidates);
 	collectDuplicateDiagnostics(index, diagnostics);
 	collectReferenceDiagnostics(index, diagnostics);
@@ -3745,7 +4029,7 @@ var validateDecisionGraph = (candidates, limits) => {
 var invalidSourceData = (path) => {
 	throw new RepositorySourceException({
 		code: "INVALID_SOURCE_DATA",
-		operation: "read-file",
+		operation: "read-file-page",
 		path,
 		retryable: false
 	});
@@ -3774,17 +4058,17 @@ var sortDecisions = (decisions) => {
 */
 var readDecisionGraph = async (repository, paths, options, signal) => {
 	options = createCoreOperationOptionsSnapshot(options);
-	const diagnostics = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const diagnostics = createCoreDiagnosticCollector(options.limits, "validate-project");
 	const candidates = [];
 	const decisions = [];
 	const readOptions = signal === void 0 ? void 0 : { signal };
 	for (const path of [...paths].sort(compareExactStrings)) {
-		const content = await repository.readFile(path, readOptions);
+		const content = await repository.readCompleteFile(path, readOptions);
 		if (!(content instanceof Uint8Array)) return invalidSourceData(path);
 		const parsed = await parseDecisionDocument({
 			content: content.slice(),
 			path
-		}, options, "inspect-project");
+		}, options, "validate-project");
 		for (const diagnostic of parsed.diagnostics) diagnostics.merge(diagnostic);
 		candidates.push({
 			decision: parsed.decision,
@@ -3860,7 +4144,7 @@ var validateDecisionRelationship = (referencedPath, pointer, context, agentId) =
 * - RESOURCE_LIMIT_EXCEEDED: The repository-level diagnostic budget was exceeded.
 */
 var validateManifestRelationships = (manifestPath, manifest, discovery, decisions, limits) => {
-	const collector = createCoreDiagnosticCollector(limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(limits, "validate-project");
 	const validAgentContextPaths = new Set(discovery.inventory.context);
 	const validTopLevelContextPaths = new Set(validAgentContextPaths);
 	if (discovery.inventory.project !== null) validTopLevelContextPaths.add(discovery.inventory.project);
@@ -3925,9 +4209,11 @@ var inspectMirror = async (repository, manifestPath, canonicalInstruction, mirro
 		return null;
 	}
 	return {
+		byteLength: mirrorResult.asset.utf8ByteLength,
 		canonicalDigest: canonicalInstruction.digest,
 		digest: mirrorResult.asset.digest,
-		path: mirrorPath
+		path: mirrorPath,
+		scalarLength: mirrorResult.asset.scalarLength
 	};
 };
 /**
@@ -3951,7 +4237,7 @@ var inspectMirror = async (repository, manifestPath, canonicalInstruction, mirro
 */
 var inspectMirrors = async (repository, manifestPath, agents, options, signal) => {
 	options = createCoreOperationOptionsSnapshot(options);
-	const collector = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(options.limits, "validate-project");
 	const agentMirrors = [];
 	const operationOptions = signal === void 0 ? void 0 : { signal };
 	for (const agent of [...agents].sort((left, right) => compareExactStrings(left.id, right.id))) {
@@ -3999,7 +4285,7 @@ var addDiagnostics$2 = (collector, diagnostics) => {
 */
 var readProjectFile = async (repository, path, options, signal) => {
 	options = createCoreOperationOptionsSnapshot(options);
-	const collector = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(options.limits, "validate-project");
 	let project = null;
 	if (path !== null) {
 		const result = await readRepositoryTextAsset(repository, path, options.limits, signal);
@@ -4040,7 +4326,7 @@ var readProjectFile = async (repository, path, options, signal) => {
 */
 var readProjectAssets = async (repository, manifest, discovery, options, signal, projectFile) => {
 	options = createCoreOperationOptionsSnapshot(options);
-	const collector = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(options.limits, "validate-project");
 	const context = [];
 	const inspectedProject = projectFile ?? await readProjectFile(repository, discovery.inventory.project, options, signal);
 	addDiagnostics$2(collector, inspectedProject.diagnostics);
@@ -4307,7 +4593,7 @@ var validateCandidate = (candidate, entry, manifestPath, collector) => {
 * - ABORTED: Repository inspection or a repository lookup was aborted.
 */
 var validateRepositoryReferences = async (repository, manifestPath, manifest, discovery, limits, signal) => {
-	const collector = createCoreDiagnosticCollector(limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(limits, "validate-project");
 	const blockedPaths = new Set(discovery.diagnostics.flatMap((diagnostic) => diagnostic.path === null ? [] : [diagnostic.path]));
 	const entryCache = /* @__PURE__ */ new Map();
 	const operationOptions = signal === void 0 ? void 0 : { signal };
@@ -4358,7 +4644,7 @@ var isBlockedPath = (path, blockedPaths) => {
 */
 var readRuntimeGuidance = async (repository, manifestPath, manifest, discovery, options, signal) => {
 	options = createCoreOperationOptionsSnapshot(options);
-	const collector = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(options.limits, "validate-project");
 	const runtimes = [];
 	const discoveredPaths = new Set(discovery.inventory.runtimeGuidance);
 	const blockedPaths = new Set(discovery.diagnostics.flatMap((diagnostic) => diagnostic.path === null ? [] : [diagnostic.path]));
@@ -4421,7 +4707,7 @@ var addDiagnostics = (collector, diagnostics) => {
 var inspectUniversalProject = async (context, options) => {
 	options = createCoreOperationOptionsSnapshot(options);
 	const { session, signal } = context;
-	const collector = createCoreDiagnosticCollector(options.limits, "inspect-project");
+	const collector = createCoreDiagnosticCollector(options.limits, "validate-project");
 	const operationOptions = signal === void 0 ? void 0 : { signal };
 	const moldeaRoot = await session.reader.getEntry(MOLDEA_ROOT, operationOptions);
 	let manifestEntry = null;
@@ -4433,9 +4719,9 @@ var inspectUniversalProject = async (context, options) => {
 		manifestEntry = await session.reader.getEntry(MANIFEST_PATH, operationOptions);
 		if (manifestEntry?.type === "file") {
 			const parsedManifest = await inspectManifestDocument({
-				content: await session.reader.readFile(MANIFEST_PATH, operationOptions),
+				content: await session.reader.readCompleteFile(MANIFEST_PATH, operationOptions),
 				path: MANIFEST_PATH
-			}, options, "inspect-project");
+			}, options, "validate-project");
 			formatVersion = parsedManifest.formatVersion;
 			runtimeLocations = parsedManifest.runtimeLocations;
 			addDiagnostics(collector, parsedManifest.diagnostics);
@@ -4493,35 +4779,35 @@ var inspectUniversalProject = async (context, options) => {
 	});
 };
 //#endregion
-//#region src/project-inspection/index.ts
+//#region src/project-validation/index.ts
 var isRecord$1 = (candidate) => {
 	return typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
 };
-var invalidArgument$1 = () => {
+var invalidArgument$2 = () => {
 	throw new CoreOperationException({
 		code: "INVALID_ARGUMENT",
-		operation: "inspect-project"
+		operation: "validate-project"
 	});
 };
 var isRepositoryReader = (candidate) => {
-	return isRecord$1(candidate) && typeof candidate["getEntry"] === "function" && typeof candidate["listEntries"] === "function" && typeof candidate["readFile"] === "function";
+	return isRecord$1(candidate) && isRecord$1(candidate["snapshot"]) && typeof candidate["snapshot"]["id"] === "string" && typeof candidate["snapshot"]["sourceKind"] === "string" && typeof candidate["compare"] === "function" && typeof candidate["getEntry"] === "function" && typeof candidate["listEntriesPage"] === "function" && typeof candidate["readFilePage"] === "function";
 };
 var isAbortSignal = (candidate) => {
 	return isRecord$1(candidate) && typeof candidate["aborted"] === "boolean" && typeof candidate["addEventListener"] === "function" && typeof candidate["removeEventListener"] === "function";
 };
 var validateInput = (candidate) => {
 	try {
-		if (!isRecord$1(candidate)) return invalidArgument$1();
+		if (!isRecord$1(candidate)) return invalidArgument$2();
 		const repository = candidate["repository"];
 		const signal = candidate["signal"];
-		if (!isRepositoryReader(repository) || signal !== void 0 && !isAbortSignal(signal)) return invalidArgument$1();
+		if (Reflect.ownKeys(candidate).some((key) => key !== "repository" && key !== "signal") || !isRepositoryReader(repository) || signal !== void 0 && !isAbortSignal(signal)) return invalidArgument$2();
 		return {
 			repository,
 			...signal === void 0 ? {} : { signal }
 		};
 	} catch (error) {
 		if (error instanceof CoreOperationException) throw error;
-		return invalidArgument$1();
+		return invalidArgument$2();
 	}
 };
 /**
@@ -4543,7 +4829,7 @@ var validateInput = (candidate) => {
 * - ABORTED: Project inspection or a repository operation was aborted.
 * - ADAPTER_EXECUTION_FAILED: A runtime adapter failed or returned an invalid result.
 */
-var inspectProject = async (input, options) => {
+var validateProjectState = async (input, options) => {
 	const validatedInput = validateInput(input);
 	const operationOptions = createCoreOperationOptionsSnapshot(options);
 	const session = createRepositoryInspectionSession(validatedInput.repository, operationOptions.limits, validatedInput.signal);
@@ -4552,28 +4838,200 @@ var inspectProject = async (input, options) => {
 		...validatedInput.signal === void 0 ? {} : { signal: validatedInput.signal }
 	}, operationOptions);
 	if (universal.project === null) return freezeRecursively({
-		diagnostics: universal.diagnostics,
-		evidence: [],
-		formatVersion: universal.formatVersion,
 		project: null,
-		valid: false
+		result: {
+			diagnostics: universal.diagnostics,
+			evidence: [],
+			formatVersion: universal.formatVersion,
+			source: validatedInput.repository.snapshot,
+			summary: null,
+			valid: false
+		}
 	});
+	const projectSummary = createProjectSummary(universal.project);
 	const availabilityDiagnostics = validateRuntimeAdapterAvailability(universal.runtimeLocations, universal.project.formatVersion, operationOptions);
 	if (availabilityDiagnostics.length > 0) return freezeRecursively({
-		diagnostics: availabilityDiagnostics,
-		evidence: [],
-		formatVersion: universal.formatVersion,
-		project: null,
-		valid: false
+		project: universal.project,
+		result: {
+			diagnostics: availabilityDiagnostics,
+			evidence: [],
+			formatVersion: universal.formatVersion,
+			source: validatedInput.repository.snapshot,
+			summary: projectSummary,
+			valid: false
+		}
 	});
 	const adapterInspection = await inspectRuntimeAdapters(universal.project, session, operationOptions, validatedInput.signal);
 	const valid = adapterInspection.diagnostics.length === 0;
 	return freezeRecursively({
-		diagnostics: adapterInspection.diagnostics,
-		evidence: adapterInspection.evidence,
-		formatVersion: universal.formatVersion,
-		project: valid ? universal.project : null,
-		valid
+		project: universal.project,
+		result: {
+			diagnostics: adapterInspection.diagnostics,
+			evidence: adapterInspection.evidence,
+			formatVersion: universal.formatVersion,
+			source: validatedInput.repository.snapshot,
+			summary: projectSummary,
+			valid
+		}
+	});
+};
+/** 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";
+var encoder = new TextEncoder();
+var invalidArgument$1 = () => {
+	throw new CoreOperationException({
+		code: "INVALID_ARGUMENT",
+		operation: "inspect-project-page"
+	});
+};
+/** Serializes the closed inspection records with recursively sorted object keys. */
+var serializeDeterministically = (candidate) => {
+	if (candidate === null || typeof candidate !== "object") {
+		const serialized = JSON.stringify(candidate);
+		return serialized === void 0 ? "null" : serialized;
+	}
+	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 createItemBaseKey = (item) => {
+	if (item.kind === "metadata") return [
+		"0",
+		item.metadata.path,
+		item.metadata.kind,
+		item.metadata.agentId ?? "",
+		item.metadata.decisionId ?? "",
+		item.metadata.digest
+	].join(":");
+	if (item.kind === "diagnostic") return [
+		"1",
+		item.diagnostic.source,
+		item.diagnostic.code,
+		item.diagnostic.path ?? "",
+		createIdentity([serializeDeterministically(item.diagnostic)])
+	].join(":");
+	return [
+		"2",
+		item.evidence.source,
+		item.evidence.kind,
+		item.evidence.agentId ?? "",
+		createIdentity([serializeDeterministically(item.evidence)])
+	].join(":");
+};
+/** Assigns stable unique keys 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")}`
+		};
+	});
+};
+var createCursorChecksum = (inspectionDigest, lastKey, view) => createIdentity([
+	CURSOR_PREFIX,
+	inspectionDigest,
+	lastKey,
+	view
+]);
+var encodeCursor = (inspectionDigest, view, lastKey) => [
+	CURSOR_PREFIX,
+	view,
+	encodeURIComponent(lastKey),
+	inspectionDigest,
+	createCursorChecksum(inspectionDigest, lastKey, view)
+].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);
+	if (match === null || match[1] !== view || match[3] !== inspectionDigest) return invalidArgument$1();
+	let lastKey;
+	try {
+		lastKey = decodeURIComponent(match[2]);
+	} catch {
+		return invalidArgument$1();
+	}
+	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 item.kind === view;
+});
+/** 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 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"
+		}))
+	]);
+	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,
+		formatVersion: state.result.formatVersion,
+		inspectionDigest,
+		page: {
+			isComplete: nextCursor === null,
+			nextCursor,
+			records,
+			totalItems: items.length
+		},
+		source: state.result.source,
+		summary: state.result.summary,
+		valid: state.result.valid,
+		view: input.view
 	});
 };
 //#endregion
@@ -4979,13 +5437,15 @@ var createCore = (options) => {
 		calculateContentDigest: (input) => {
 			return calculateContentDigest(input, createCoreOperationOptionsSnapshot(snapshot).limits);
 		},
-		inspectProject: (input) => inspectProject(input, createCoreOperationOptionsSnapshot(snapshot)),
+		inspectProjectPage: (input) => inspectProjectPage(input, createCoreOperationOptionsSnapshot(snapshot)),
+		validateProject: (input) => validateProject(input, createCoreOperationOptionsSnapshot(snapshot)),
 		matchManifestScope: (input) => matchManifestScope(input, createCoreOperationOptionsSnapshot(snapshot)),
 		normalizeText: (input) => {
 			return normalizeTextDocument(input, createCoreOperationOptionsSnapshot(snapshot).limits, "normalize-text");
 		},
 		parseDecision: (input) => parseDecisionDocument(input, createCoreOperationOptionsSnapshot(snapshot)),
-		parseManifest: (input) => parseManifestDocument(input, createCoreOperationOptionsSnapshot(snapshot))
+		parseManifest: (input) => parseManifestDocument(input, createCoreOperationOptionsSnapshot(snapshot)),
+		readCanonicalContentPage: (input) => readCanonicalContentPage(input, createCoreOperationOptionsSnapshot(snapshot))
 	});
 };
 //#endregion