@moldea.ai/core 4.0.0 → 4.0.1

package/README.md

@@ -69,7 +69,7 @@ const result = await core.validateProject({ repository });
 
 `createProjectInspection` validates the snapshot once, prepares one immutable content-free record set, and returns synchronous bounded page reads for the `metadata`, `diagnostics`, `evidence`, and `all` views. The `metadata` and `all` views include one independently keyed `agent` record per canonical agent with exactly its `agentId` and manifest-declared `runtimeId`, distinct from asset metadata and adapter evidence. Each page uses a semantic continuation cursor tied to the complete inspection digest and view. Page reads perform no repository access, revalidation, sorting, digesting, or adapter execution.
 
-The prepared inspection retains only its content-free records, summary, source identity, deterministic resource accounting, and page indexes. It does not retain canonical document bodies. `readCanonicalContentPage` is the only Core project operation that returns a body, and it requires an explicit canonical `/moldea/**` file path, byte offset, and byte bound. Returned chunks end at a complete UTF-8 scalar.
+The prepared inspection retains only its content-free records, summary, source identity, deterministic resource accounting, and page indexes. Core preflights the complete logical cost before it constructs the prepared collections, indexes, or digest. It does not retain canonical document bodies. `readCanonicalContentPage` is the only Core project operation that returns a body, and it requires an explicit canonical `/moldea/**` file path, byte offset, and byte bound. Returned chunks end at a complete UTF-8 scalar.
 
 ## Per-agent runtime adapters
 
@@ -79,7 +79,7 @@ Adapter evidence and diagnostics are validated, normalized, deduplicated, sorted
 
 ## Resource and trust boundaries
 
-Core uses independent limits for distinct entries, total bytes read, per-file bytes, manifest bytes, logical retained bytes, diagnostics, and evidence. The default logical retained-memory ceiling is 512 MiB. Project inspection accounts for canonical validation state, transient read pages, and prepared content-free records before completing, and reports deterministic logical usage without exposing document bodies. The adapter-facing repository adds per-page entry and byte limits. Core executes no repository code, follows no symlink, receives no host path or source credential, and returns logical paths only.
+Core uses independent limits for distinct entries, total bytes read, per-file bytes, manifest bytes, logical retained bytes, diagnostics, and evidence. The default logical retained-memory ceiling is 512 MiB. Project inspection accounts for canonical validation state, complete adapter file buffers, transient read pages, and prepared content-free records before completing, and reports deterministic logical usage without exposing document bodies. A complete adapter buffer is reserved before allocation and remains charged for the inspection lifetime. The adapter-facing repository adds per-page entry and byte limits. Core executes no repository code, follows no symlink, receives no host path or source credential, and returns logical paths only.
 
 Every `RESOURCE_LIMIT_EXCEEDED` exception identifies the exceeded limit, its configured maximum, the observed or projected usage, and the stable `reduce-input-or-increase-limit` next action. Core refuses the operation before allocating retained state beyond the applicable ceiling.
 

package/dist/adapter-repository/index.d.ts

@@ -1,6 +1,24 @@
 import { type IRepositoryEntry, type IRepositoryOperationOptions, type IRepositoryPath } from '@moldea.ai/repository';
 import type { IRuntimeAdapterRepository } from '../adapter/index.js';
-/** Reads one complete adapter source file through bounded repository pages. */
+/**
+ * Reads one complete adapter source file through bounded repository pages.
+ * @param repository The Core-created repository for the current adapter invocation.
+ * @param path The exact source file path.
+ * @param options Optional cancellation controls.
+ * @returns A promise resolving to one detached complete source buffer.
+ * @throws
+ * - INVALID_REPOSITORY_PATH: The repository path is invalid.
+ * - ENTRY_NOT_FOUND: The requested repository entry was not found.
+ * - ENTRY_NOT_FILE: The requested repository entry is not a file.
+ * - INVALID_PAGE_REQUEST: The repository page request is invalid.
+ * - ACCESS_DENIED: Access to the repository source was denied.
+ * - SOURCE_UNAVAILABLE: The repository source is unavailable.
+ * - SNAPSHOT_CHANGED: The repository snapshot changed during the operation.
+ * - INVALID_SOURCE_DATA: The repository source returned invalid data.
+ * - RESOURCE_LIMIT_EXCEEDED: A named repository resource limit was exceeded.
+ * - ABORTED: The repository operation was aborted.
+ * - RESOURCE_LIMIT_EXCEEDED: A Core resource limit was exceeded.
+ */
 export declare const readRuntimeAdapterFile: (repository: IRuntimeAdapterRepository, path: IRepositoryPath, options?: IRepositoryOperationOptions) => Promise<Uint8Array>;
 /** Iterates one adapter-scoped descendant listing through bounded pages. */
 export declare const iterateRuntimeAdapterEntries: (repository: IRuntimeAdapterRepository, options?: IRepositoryOperationOptions & {

package/dist/adapter-repository/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter-repository/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AA8BrE,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,GACjC,YAAY,yBAAyB,EACrC,MAAM,eAAe,EACrB,UAAU,2BAA2B,KACpC,OAAO,CAAC,UAAU,CAwEpB,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,GACvC,YAAY,yBAAyB,EACrC,UAAU,2BAA2B,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,KAC5E,aAAa,CAAC,gBAAgB,CA6DhC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter-repository/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,gBAAgB,EACrB,KAAK,2BAA2B,EAChC,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AA+BrE;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,sBAAsB,GACjC,YAAY,yBAAyB,EACrC,MAAM,eAAe,EACrB,UAAU,2BAA2B,KACpC,OAAO,CAAC,UAAU,CAyEpB,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,4BAA4B,GACvC,YAAY,yBAAyB,EACrC,UAAU,2BAA2B,GAAG;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAA;CAAE,KAC5E,aAAa,CAAC,gBAAgB,CA6DhC,CAAC"}

package/dist/adapter-retained-memory/index.d.ts

@@ -0,0 +1,8 @@
+import type { IRuntimeAdapterRepository } from '../adapter/index.js';
+type IRetainedByteReservation = (byteLength: number) => void;
+/** Registers the retained-memory reservation owned by one inspection session. */
+export declare const registerRuntimeAdapterRetainedByteReservation: (repository: IRuntimeAdapterRepository, reserve: IRetainedByteReservation) => void;
+/** Reserves a complete adapter-owned buffer when Core owns the repository session. */
+export declare const reserveRuntimeAdapterRetainedBytesIfTracked: (repository: IRuntimeAdapterRepository, byteLength: number) => void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter-retained-memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter-retained-memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AACrE,KAAK,wBAAwB,GAAG,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;AAK7D,iFAAiF;AACjF,eAAO,MAAM,6CAA6C,GACxD,YAAY,yBAAyB,EACrC,SAAS,wBAAwB,KAChC,IAMF,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,2CAA2C,GACtD,YAAY,yBAAyB,EACrC,YAAY,MAAM,KACjB,IAMF,CAAC"}

package/dist/adapter.js

@@ -1,4 +1,4 @@
-import { n as CoreOperationException } from "./chunks/exceptions-C_KfCIjE.js";
+import { i as reserveRuntimeAdapterRetainedBytesIfTracked, n as CoreOperationException } from "./chunks/exceptions-HS9ofVy2.js";
 import { REPOSITORY_ROOT, RepositorySourceException, compareRepositoryPaths, parseRepositoryPath } from "@moldea.ai/repository";
 //#region src/adapter-repository/index.ts
 var invalidSourceData = (operation, path) => {
@@ -19,7 +19,25 @@ var throwResourceLimitExceeded = (limit, limitMaximum, observedUsage) => {
 		operation: "validate-project"
 	});
 };
-/** Reads one complete adapter source file through bounded repository pages. */
+/**
+* Reads one complete adapter source file through bounded repository pages.
+* @param repository The Core-created repository for the current adapter invocation.
+* @param path The exact source file path.
+* @param options Optional cancellation controls.
+* @returns A promise resolving to one detached complete source buffer.
+* @throws
+* - INVALID_REPOSITORY_PATH: The repository path is invalid.
+* - ENTRY_NOT_FOUND: The requested repository entry was not found.
+* - ENTRY_NOT_FILE: The requested repository entry is not a file.
+* - INVALID_PAGE_REQUEST: The repository page request is invalid.
+* - ACCESS_DENIED: Access to the repository source was denied.
+* - SOURCE_UNAVAILABLE: The repository source is unavailable.
+* - SNAPSHOT_CHANGED: The repository snapshot changed during the operation.
+* - INVALID_SOURCE_DATA: The repository source returned invalid data.
+* - RESOURCE_LIMIT_EXCEEDED: A named repository resource limit was exceeded.
+* - ABORTED: The repository operation was aborted.
+* - RESOURCE_LIMIT_EXCEEDED: A Core resource limit was exceeded.
+*/
 var readRuntimeAdapterFile = async (repository, path, options) => {
 	const parsedPath = parseRepositoryPath(path);
 	const entry = await repository.getEntry(parsedPath, options);
@@ -36,6 +54,7 @@ var readRuntimeAdapterFile = async (repository, path, options) => {
 		retryable: false
 	});
 	if (entry.byteLength > repository.limits.maxFileBytes) return throwResourceLimitExceeded("maxFileBytes", repository.limits.maxFileBytes, entry.byteLength);
+	reserveRuntimeAdapterRetainedBytesIfTracked(repository, entry.byteLength);
 	const content = new Uint8Array(entry.byteLength);
 	let offset = 0;
 	let isFirstPage = true;

package/dist/adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.js","names":[],"sources":["../src/adapter-repository/index.ts"],"sourcesContent":["import {\n  REPOSITORY_ROOT,\n  RepositorySourceException,\n  compareRepositoryPaths,\n  parseRepositoryPath,\n  type IRepositoryEntry,\n  type IRepositoryOperationOptions,\n  type IRepositoryPath,\n} from '@moldea.ai/repository';\n\nimport type { IRuntimeAdapterRepository } from '../adapter/index.js';\nimport { CoreOperationException } from '../exceptions/index.js';\n\nconst invalidSourceData = (\n  operation: 'list-entries-page' | 'read-file-page',\n  path: IRepositoryPath,\n): never => {\n  throw new RepositorySourceException({\n    code: 'INVALID_SOURCE_DATA',\n    operation,\n    path,\n    retryable: false,\n  });\n};\n\nconst throwResourceLimitExceeded = (\n  limit: 'maxEntries' | 'maxFileBytes' | 'maxTotalBytesRead',\n  limitMaximum: number,\n  observedUsage: number,\n): never => {\n  throw new CoreOperationException({\n    code: 'RESOURCE_LIMIT_EXCEEDED',\n    limit,\n    limitMaximum,\n    nextAction: 'reduce-input-or-increase-limit',\n    observedUsage,\n    operation: 'validate-project',\n  });\n};\n\n/** Reads one complete adapter source file through bounded repository pages. */\nexport const readRuntimeAdapterFile = async (\n  repository: IRuntimeAdapterRepository,\n  path: IRepositoryPath,\n  options?: IRepositoryOperationOptions,\n): Promise<Uint8Array> => {\n  const parsedPath = parseRepositoryPath(path);\n  const entry = await repository.getEntry(parsedPath, options);\n\n  if (entry === null) {\n    throw new RepositorySourceException({\n      code: 'ENTRY_NOT_FOUND',\n      operation: 'read-file-page',\n      path: parsedPath,\n      retryable: false,\n    });\n  }\n\n  if (entry.type !== 'file' || entry.byteLength === null) {\n    throw new RepositorySourceException({\n      code: 'ENTRY_NOT_FILE',\n      operation: 'read-file-page',\n      path: parsedPath,\n      retryable: false,\n    });\n  }\n\n  if (entry.byteLength > repository.limits.maxFileBytes) {\n    return throwResourceLimitExceeded(\n      'maxFileBytes',\n      repository.limits.maxFileBytes,\n      entry.byteLength,\n    );\n  }\n\n  const content = new Uint8Array(entry.byteLength);\n  let offset = 0;\n  let isFirstPage = true;\n\n  while (isFirstPage || offset < entry.byteLength) {\n    isFirstPage = false;\n    options?.signal?.throwIfAborted();\n    const page = await repository.readFilePage(parsedPath, {\n      maxBytes: Math.min(repository.limits.maxPageBytes, Math.max(1, entry.byteLength - offset)),\n      offset,\n      ...(options?.signal === undefined ? {} : { signal: options.signal }),\n    });\n\n    if (\n      page.snapshot.id !== repository.snapshot.id ||\n      page.offset !== offset ||\n      page.totalBytes !== entry.byteLength ||\n      !(page.bytes instanceof Uint8Array) ||\n      page.bytes.byteLength > repository.limits.maxPageBytes ||\n      page.bytes.byteLength > content.byteLength - offset ||\n      (page.bytes.byteLength === 0 && !page.isComplete)\n    ) {\n      return invalidSourceData('read-file-page', parsedPath);\n    }\n\n    content.set(page.bytes, offset);\n    offset += page.bytes.byteLength;\n\n    if (page.isComplete) {\n      if (page.nextOffset !== null || offset !== content.byteLength) {\n        return invalidSourceData('read-file-page', parsedPath);\n      }\n\n      return content;\n    }\n\n    if (page.nextOffset !== offset) {\n      return invalidSourceData('read-file-page', parsedPath);\n    }\n  }\n\n  return invalidSourceData('read-file-page', parsedPath);\n};\n\n/** Iterates one adapter-scoped descendant listing through bounded pages. */\nexport const iterateRuntimeAdapterEntries = (\n  repository: IRuntimeAdapterRepository,\n  options?: IRepositoryOperationOptions & { readonly prefix?: IRepositoryPath },\n): AsyncIterable<IRepositoryEntry> => {\n  const prefix =\n    options?.prefix === undefined ? REPOSITORY_ROOT : parseRepositoryPath(options.prefix);\n\n  return {\n    async *[Symbol.asyncIterator](): AsyncIterator<IRepositoryEntry> {\n      let cursor: string | undefined;\n      let entryCount = 0;\n      let previousPath: IRepositoryPath | null = null;\n\n      do {\n        options?.signal?.throwIfAborted();\n        const page = await repository.listEntriesPage({\n          ...(cursor === undefined ? {} : { cursor }),\n          maxEntries: repository.limits.maxPageEntries,\n          prefix,\n          ...(options?.signal === undefined ? {} : { signal: options.signal }),\n        });\n\n        if (\n          page.snapshot.id !== repository.snapshot.id ||\n          page.entries.length > repository.limits.maxPageEntries ||\n          (page.entries.length === 0 && !page.isComplete)\n        ) {\n          return invalidSourceData('list-entries-page', prefix);\n        }\n\n        for (const entry of page.entries) {\n          if (previousPath !== null && compareRepositoryPaths(previousPath, entry.path) >= 0) {\n            return invalidSourceData('list-entries-page', entry.path);\n          }\n\n          entryCount += 1;\n          if (entryCount > repository.limits.maxEntries) {\n            return throwResourceLimitExceeded(\n              'maxEntries',\n              repository.limits.maxEntries,\n              entryCount,\n            );\n          }\n\n          previousPath = entry.path;\n          yield entry;\n        }\n\n        if (page.isComplete) {\n          if (page.nextCursor !== null) {\n            return invalidSourceData('list-entries-page', prefix);\n          }\n\n          return;\n        }\n\n        if (page.nextCursor === null || page.nextCursor === cursor) {\n          return invalidSourceData('list-entries-page', prefix);\n        }\n\n        cursor = page.nextCursor;\n      } while (true);\n    },\n  };\n};\n"],"mappings":"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"}
+{"version":3,"file":"adapter.js","names":[],"sources":["../src/adapter-repository/index.ts"],"sourcesContent":["import {\n  REPOSITORY_ROOT,\n  RepositorySourceException,\n  compareRepositoryPaths,\n  parseRepositoryPath,\n  type IRepositoryEntry,\n  type IRepositoryOperationOptions,\n  type IRepositoryPath,\n} from '@moldea.ai/repository';\n\nimport type { IRuntimeAdapterRepository } from '../adapter/index.js';\nimport { reserveRuntimeAdapterRetainedBytesIfTracked } from '../adapter-retained-memory/index.js';\nimport { CoreOperationException } from '../exceptions/index.js';\n\nconst invalidSourceData = (\n  operation: 'list-entries-page' | 'read-file-page',\n  path: IRepositoryPath,\n): never => {\n  throw new RepositorySourceException({\n    code: 'INVALID_SOURCE_DATA',\n    operation,\n    path,\n    retryable: false,\n  });\n};\n\nconst throwResourceLimitExceeded = (\n  limit: 'maxEntries' | 'maxFileBytes' | 'maxTotalBytesRead',\n  limitMaximum: number,\n  observedUsage: number,\n): never => {\n  throw new CoreOperationException({\n    code: 'RESOURCE_LIMIT_EXCEEDED',\n    limit,\n    limitMaximum,\n    nextAction: 'reduce-input-or-increase-limit',\n    observedUsage,\n    operation: 'validate-project',\n  });\n};\n\n/**\n * Reads one complete adapter source file through bounded repository pages.\n * @param repository The Core-created repository for the current adapter invocation.\n * @param path The exact source file path.\n * @param options Optional cancellation controls.\n * @returns A promise resolving to one detached complete source buffer.\n * @throws\n * - INVALID_REPOSITORY_PATH: The repository path is invalid.\n * - ENTRY_NOT_FOUND: The requested repository entry was not found.\n * - ENTRY_NOT_FILE: The requested repository entry is not a file.\n * - INVALID_PAGE_REQUEST: The repository page request is invalid.\n * - ACCESS_DENIED: Access to the repository source was denied.\n * - SOURCE_UNAVAILABLE: The repository source is unavailable.\n * - SNAPSHOT_CHANGED: The repository snapshot changed during the operation.\n * - INVALID_SOURCE_DATA: The repository source returned invalid data.\n * - RESOURCE_LIMIT_EXCEEDED: A named repository resource limit was exceeded.\n * - ABORTED: The repository operation was aborted.\n * - RESOURCE_LIMIT_EXCEEDED: A Core resource limit was exceeded.\n */\nexport const readRuntimeAdapterFile = async (\n  repository: IRuntimeAdapterRepository,\n  path: IRepositoryPath,\n  options?: IRepositoryOperationOptions,\n): Promise<Uint8Array> => {\n  const parsedPath = parseRepositoryPath(path);\n  const entry = await repository.getEntry(parsedPath, options);\n\n  if (entry === null) {\n    throw new RepositorySourceException({\n      code: 'ENTRY_NOT_FOUND',\n      operation: 'read-file-page',\n      path: parsedPath,\n      retryable: false,\n    });\n  }\n\n  if (entry.type !== 'file' || entry.byteLength === null) {\n    throw new RepositorySourceException({\n      code: 'ENTRY_NOT_FILE',\n      operation: 'read-file-page',\n      path: parsedPath,\n      retryable: false,\n    });\n  }\n\n  if (entry.byteLength > repository.limits.maxFileBytes) {\n    return throwResourceLimitExceeded(\n      'maxFileBytes',\n      repository.limits.maxFileBytes,\n      entry.byteLength,\n    );\n  }\n\n  reserveRuntimeAdapterRetainedBytesIfTracked(repository, entry.byteLength);\n  const content = new Uint8Array(entry.byteLength);\n  let offset = 0;\n  let isFirstPage = true;\n\n  while (isFirstPage || offset < entry.byteLength) {\n    isFirstPage = false;\n    options?.signal?.throwIfAborted();\n    const page = await repository.readFilePage(parsedPath, {\n      maxBytes: Math.min(repository.limits.maxPageBytes, Math.max(1, entry.byteLength - offset)),\n      offset,\n      ...(options?.signal === undefined ? {} : { signal: options.signal }),\n    });\n\n    if (\n      page.snapshot.id !== repository.snapshot.id ||\n      page.offset !== offset ||\n      page.totalBytes !== entry.byteLength ||\n      !(page.bytes instanceof Uint8Array) ||\n      page.bytes.byteLength > repository.limits.maxPageBytes ||\n      page.bytes.byteLength > content.byteLength - offset ||\n      (page.bytes.byteLength === 0 && !page.isComplete)\n    ) {\n      return invalidSourceData('read-file-page', parsedPath);\n    }\n\n    content.set(page.bytes, offset);\n    offset += page.bytes.byteLength;\n\n    if (page.isComplete) {\n      if (page.nextOffset !== null || offset !== content.byteLength) {\n        return invalidSourceData('read-file-page', parsedPath);\n      }\n\n      return content;\n    }\n\n    if (page.nextOffset !== offset) {\n      return invalidSourceData('read-file-page', parsedPath);\n    }\n  }\n\n  return invalidSourceData('read-file-page', parsedPath);\n};\n\n/** Iterates one adapter-scoped descendant listing through bounded pages. */\nexport const iterateRuntimeAdapterEntries = (\n  repository: IRuntimeAdapterRepository,\n  options?: IRepositoryOperationOptions & { readonly prefix?: IRepositoryPath },\n): AsyncIterable<IRepositoryEntry> => {\n  const prefix =\n    options?.prefix === undefined ? REPOSITORY_ROOT : parseRepositoryPath(options.prefix);\n\n  return {\n    async *[Symbol.asyncIterator](): AsyncIterator<IRepositoryEntry> {\n      let cursor: string | undefined;\n      let entryCount = 0;\n      let previousPath: IRepositoryPath | null = null;\n\n      do {\n        options?.signal?.throwIfAborted();\n        const page = await repository.listEntriesPage({\n          ...(cursor === undefined ? {} : { cursor }),\n          maxEntries: repository.limits.maxPageEntries,\n          prefix,\n          ...(options?.signal === undefined ? {} : { signal: options.signal }),\n        });\n\n        if (\n          page.snapshot.id !== repository.snapshot.id ||\n          page.entries.length > repository.limits.maxPageEntries ||\n          (page.entries.length === 0 && !page.isComplete)\n        ) {\n          return invalidSourceData('list-entries-page', prefix);\n        }\n\n        for (const entry of page.entries) {\n          if (previousPath !== null && compareRepositoryPaths(previousPath, entry.path) >= 0) {\n            return invalidSourceData('list-entries-page', entry.path);\n          }\n\n          entryCount += 1;\n          if (entryCount > repository.limits.maxEntries) {\n            return throwResourceLimitExceeded(\n              'maxEntries',\n              repository.limits.maxEntries,\n              entryCount,\n            );\n          }\n\n          previousPath = entry.path;\n          yield entry;\n        }\n\n        if (page.isComplete) {\n          if (page.nextCursor !== null) {\n            return invalidSourceData('list-entries-page', prefix);\n          }\n\n          return;\n        }\n\n        if (page.nextCursor === null || page.nextCursor === cursor) {\n          return invalidSourceData('list-entries-page', prefix);\n        }\n\n        cursor = page.nextCursor;\n      } while (true);\n    },\n  };\n};\n"],"mappings":"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"}

package/dist/chunks/{exceptions-C_KfCIjE.js → exceptions-HS9ofVy2.js}

@@ -1,4 +1,17 @@
 import { Exception } from "error-message-utils";
+//#region src/adapter-retained-memory/index.ts
+var retainedByteReservations = /* @__PURE__ */ new WeakMap();
+/** Registers the retained-memory reservation owned by one inspection session. */
+var registerRuntimeAdapterRetainedByteReservation = (repository, reserve) => {
+	if (retainedByteReservations.has(repository)) throw new TypeError("The runtime adapter repository is already registered.");
+	retainedByteReservations.set(repository, reserve);
+};
+/** Reserves a complete adapter-owned buffer when Core owns the repository session. */
+var reserveRuntimeAdapterRetainedBytesIfTracked = (repository, byteLength) => {
+	const reserve = retainedByteReservations.get(repository);
+	if (reserve !== void 0) reserve(byteLength);
+};
+//#endregion
 //#region src/exceptions/index.ts
 var CONFIGURATION_ERROR_MESSAGES = {
 	DUPLICATE_ADAPTER_ID: "A runtime adapter ID is registered more than once.",
@@ -72,6 +85,6 @@ var CoreOperationException = class extends Exception {
 	}
 };
 //#endregion
-export { CoreOperationException as n, CoreConfigurationException as t };
+export { reserveRuntimeAdapterRetainedBytesIfTracked as i, CoreOperationException as n, registerRuntimeAdapterRetainedByteReservation as r, CoreConfigurationException as t };
 
-//# sourceMappingURL=exceptions-C_KfCIjE.js.map
+//# sourceMappingURL=exceptions-HS9ofVy2.js.map

package/dist/chunks/exceptions-HS9ofVy2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions-HS9ofVy2.js","names":[],"sources":["../../src/adapter-retained-memory/index.ts","../../src/exceptions/index.ts"],"sourcesContent":["import type { IRuntimeAdapterRepository } from '../adapter/index.js';\ntype IRetainedByteReservation = (byteLength: number) => void;\n\n// reservations belong to Core-created adapter repositories and remain private to the session\nconst retainedByteReservations = new WeakMap<IRuntimeAdapterRepository, IRetainedByteReservation>();\n\n/** Registers the retained-memory reservation owned by one inspection session. */\nexport const registerRuntimeAdapterRetainedByteReservation = (\n  repository: IRuntimeAdapterRepository,\n  reserve: IRetainedByteReservation,\n): void => {\n  if (retainedByteReservations.has(repository)) {\n    throw new TypeError('The runtime adapter repository is already registered.');\n  }\n\n  retainedByteReservations.set(repository, reserve);\n};\n\n/** Reserves a complete adapter-owned buffer when Core owns the repository session. */\nexport const reserveRuntimeAdapterRetainedBytesIfTracked = (\n  repository: IRuntimeAdapterRepository,\n  byteLength: number,\n): void => {\n  const reserve = retainedByteReservations.get(repository);\n\n  if (reserve !== undefined) {\n    reserve(byteLength);\n  }\n};\n","import { Exception } from 'error-message-utils';\n\n// stable configuration and operation failure codes\nexport type ICoreConfigurationErrorCode =\n  | 'DUPLICATE_ADAPTER_ID'\n  | 'RESERVED_ADAPTER_ID'\n  | 'INVALID_ADAPTER_DEFINITION'\n  | 'INVALID_RESOURCE_LIMIT';\n\nexport type ICoreOperationErrorCode =\n  | 'INVALID_ARGUMENT'\n  | 'ABORTED'\n  | 'RESOURCE_LIMIT_EXCEEDED'\n  | 'ADAPTER_EXECUTION_FAILED'\n  | 'CONTENT_INVALID';\n\nexport type ICoreOperation =\n  | 'create-core'\n  | 'normalize-text'\n  | 'calculate-content-digest'\n  | 'parse-manifest'\n  | 'match-manifest-scope'\n  | 'parse-decision'\n  | 'create-project-inspection'\n  | 'read-canonical-content-page'\n  | 'validate-project'\n  | 'validate-adapter';\n\n// safe construction options for exported Core exceptions\nexport interface ICoreConfigurationExceptionOptions {\n  readonly code: ICoreConfigurationErrorCode;\n  readonly operation: ICoreOperation;\n  readonly adapterId?: string;\n  readonly cause?: unknown;\n}\n\ninterface ICoreOperationExceptionOptionsBase {\n  readonly operation: ICoreOperation;\n  readonly adapterId?: string;\n  readonly agentId?: string;\n  readonly cause?: unknown;\n}\n\n// complete resource-refusal metadata required by Core 4\nexport type ICoreResourceLimitNextAction = 'reduce-input-or-increase-limit';\n\nexport type ICoreOperationExceptionOptions = ICoreOperationExceptionOptionsBase &\n  (\n    | {\n        readonly code: 'RESOURCE_LIMIT_EXCEEDED';\n        readonly limit: string;\n        readonly limitMaximum: number;\n        readonly nextAction: ICoreResourceLimitNextAction;\n        readonly observedUsage: number;\n      }\n    | {\n        readonly code: Exclude<ICoreOperationErrorCode, 'RESOURCE_LIMIT_EXCEEDED'>;\n        readonly limit?: never;\n        readonly limitMaximum?: never;\n        readonly nextAction?: never;\n        readonly observedUsage?: never;\n      }\n  );\n\nconst CONFIGURATION_ERROR_MESSAGES = {\n  DUPLICATE_ADAPTER_ID: 'A runtime adapter ID is registered more than once.',\n  INVALID_ADAPTER_DEFINITION: 'A runtime adapter definition is invalid.',\n  INVALID_RESOURCE_LIMIT: 'A Core resource limit is invalid.',\n  RESERVED_ADAPTER_ID: 'A reserved runtime adapter ID was supplied.',\n} as const satisfies Readonly<Record<ICoreConfigurationErrorCode, string>>;\n\nconst OPERATION_ERROR_MESSAGES = {\n  ABORTED: 'The Core operation was aborted.',\n  ADAPTER_EXECUTION_FAILED: 'A runtime adapter failed during inspection.',\n  CONTENT_INVALID: 'The canonical content is not valid UTF-8 text.',\n  INVALID_ARGUMENT: 'The Core operation received an invalid argument.',\n  RESOURCE_LIMIT_EXCEEDED: 'A Core resource limit was exceeded.',\n} as const satisfies Readonly<Record<ICoreOperationErrorCode, string>>;\n\nconst OPERATION_ERROR_RETRYABILITY = {\n  ABORTED: true,\n  ADAPTER_EXECUTION_FAILED: false,\n  CONTENT_INVALID: false,\n  INVALID_ARGUMENT: false,\n  RESOURCE_LIMIT_EXCEEDED: false,\n} as const satisfies Readonly<Record<ICoreOperationErrorCode, boolean>>;\n\nconst attachCause = (exception: Error, cause: unknown): void => {\n  if (cause === undefined) {\n    return;\n  }\n\n  Object.defineProperty(exception, 'cause', {\n    configurable: true,\n    enumerable: false,\n    value: cause,\n    writable: false,\n  });\n};\n\n/** Represents invalid immutable Core configuration. */\nexport class CoreConfigurationException extends Exception {\n  public override readonly code: ICoreConfigurationErrorCode;\n\n  public readonly operation: ICoreOperation;\n\n  public readonly adapterId: string | null;\n\n  /** Creates a configuration exception with safe adapter metadata. */\n  public constructor(options: ICoreConfigurationExceptionOptions) {\n    super(CONFIGURATION_ERROR_MESSAGES[options.code], options.code);\n    this.code = options.code;\n    this.name = 'CoreConfigurationException';\n    this.operation = options.operation;\n    this.adapterId = options.adapterId ?? null;\n    attachCause(this, options.cause);\n  }\n}\n\n/** Represents an operational failure that prevented Core from completing. */\nexport class CoreOperationException extends Exception {\n  public override readonly code: ICoreOperationErrorCode;\n\n  public readonly operation: ICoreOperation;\n\n  public readonly retryable: boolean;\n\n  public readonly adapterId: string | null;\n\n  public readonly agentId: string | null;\n\n  public readonly limit: string | null;\n\n  public readonly limitMaximum: number | null;\n\n  public readonly nextAction: ICoreResourceLimitNextAction | null;\n\n  public readonly observedUsage: number | null;\n\n  /** Creates an operation exception with derived retry and safe scope metadata. */\n  public constructor(options: ICoreOperationExceptionOptions) {\n    super(OPERATION_ERROR_MESSAGES[options.code], options.code);\n    this.code = options.code;\n    this.name = 'CoreOperationException';\n    this.operation = options.operation;\n    this.retryable = OPERATION_ERROR_RETRYABILITY[options.code];\n    this.adapterId = options.adapterId ?? null;\n    this.agentId = options.agentId ?? null;\n    this.limit = options.limit ?? null;\n    this.limitMaximum = options.limitMaximum ?? null;\n    this.nextAction = options.nextAction ?? null;\n    this.observedUsage = options.observedUsage ?? null;\n    attachCause(this, options.cause);\n  }\n}\n"],"mappings":";;AAIA,IAAM,2CAA2B,IAAI,QAA6D;;AAGlG,IAAa,iDACX,YACA,YACS;CACT,IAAI,yBAAyB,IAAI,UAAU,GACzC,MAAM,IAAI,UAAU,uDAAuD;CAG7E,yBAAyB,IAAI,YAAY,OAAO;AAClD;;AAGA,IAAa,+CACX,YACA,eACS;CACT,MAAM,UAAU,yBAAyB,IAAI,UAAU;CAEvD,IAAI,YAAY,KAAA,GACd,QAAQ,UAAU;AAEtB;;;ACoCA,IAAM,+BAA+B;CACnC,sBAAsB;CACtB,4BAA4B;CAC5B,wBAAwB;CACxB,qBAAqB;AACvB;AAEA,IAAM,2BAA2B;CAC/B,SAAS;CACT,0BAA0B;CAC1B,iBAAiB;CACjB,kBAAkB;CAClB,yBAAyB;AAC3B;AAEA,IAAM,+BAA+B;CACnC,SAAS;CACT,0BAA0B;CAC1B,iBAAiB;CACjB,kBAAkB;CAClB,yBAAyB;AAC3B;AAEA,IAAM,eAAe,WAAkB,UAAyB;CAC9D,IAAI,UAAU,KAAA,GACZ;CAGF,OAAO,eAAe,WAAW,SAAS;EACxC,cAAc;EACd,YAAY;EACZ,OAAO;EACP,UAAU;CACZ,CAAC;AACH;;AAGA,IAAa,6BAAb,cAAgD,UAAU;CACxD;CAEA;CAEA;;CAGA,YAAmB,SAA6C;EAC9D,MAAM,6BAA6B,QAAQ,OAAO,QAAQ,IAAI;EAC9D,KAAK,OAAO,QAAQ;EACpB,KAAK,OAAO;EACZ,KAAK,YAAY,QAAQ;EACzB,KAAK,YAAY,QAAQ,aAAa;EACtC,YAAY,MAAM,QAAQ,KAAK;CACjC;AACF;;AAGA,IAAa,yBAAb,cAA4C,UAAU;CACpD;CAEA;CAEA;CAEA;CAEA;CAEA;CAEA;CAEA;CAEA;;CAGA,YAAmB,SAAyC;EAC1D,MAAM,yBAAyB,QAAQ,OAAO,QAAQ,IAAI;EAC1D,KAAK,OAAO,QAAQ;EACpB,KAAK,OAAO;EACZ,KAAK,YAAY,QAAQ;EACzB,KAAK,YAAY,6BAA6B,QAAQ;EACtD,KAAK,YAAY,QAAQ,aAAa;EACtC,KAAK,UAAU,QAAQ,WAAW;EAClC,KAAK,QAAQ,QAAQ,SAAS;EAC9B,KAAK,eAAe,QAAQ,gBAAgB;EAC5C,KAAK,aAAa,QAAQ,cAAc;EACxC,KAAK,gBAAgB,QAAQ,iBAAiB;EAC9C,YAAY,MAAM,QAAQ,KAAK;CACjC;AACF"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { n as CoreOperationException, t as CoreConfigurationException } from "./chunks/exceptions-C_KfCIjE.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
@@ -2312,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) => ({
@@ -2329,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,
@@ -2349,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) => ({
@@ -3148,6 +3149,7 @@ var createRepositoryInspectionSession = (repository, limits, signal) => {
 		readFilePage: readAdapterFilePage,
 		snapshot: repository.snapshot
 	});
+	registerRuntimeAdapterRetainedByteReservation(adapterRepository, reserveRetainedBytes);
 	return Object.freeze({
 		adapterRepository,
 		getResourceUsage: () => Object.freeze({
@@ -4975,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",
@@ -5007,19 +5011,19 @@ var createItemBaseKey = (item) => {
 };
 /** 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,
@@ -5058,17 +5062,71 @@ var addRetainedBytes = (current, additional, retainedBeforePreparation, maximum)
 	if (!Number.isSafeInteger(additional) || additional < 0 || !Number.isSafeInteger(projectedUsage) || projectedUsage > maximum) return resourceLimitExceeded$1(maximum, Number.isSafeInteger(projectedUsage) ? projectedUsage : Number.MAX_SAFE_INTEGER);
 	return current + additional;
 };
-/** Calculates deterministic logical bytes retained by prepared records and view indexes. */
-var calculatePreparedBytes = (items, views, header, retainedBeforePreparation, maximum) => {
+/** 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);
-	for (const { item, key } of items) {
+	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, retainedBeforePreparation, maximum);
-	}
-	bytes = addRetainedBytes(bytes, encoder.encode(serializeDeterministically(header)).byteLength * PREPARED_TEXT_BYTE_MULTIPLIER, retainedBeforePreparation, maximum);
-	bytes = addRetainedBytes(bytes, (views.diagnostics.length + views.evidence.length + views.metadata.length) * PREPARED_VIEW_REFERENCE_BYTES, retainedBeforePreparation, maximum);
-	return bytes;
+		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;
@@ -5085,23 +5143,9 @@ var findStartIndex = (items, lastKey) => {
 };
 /** Creates the returned inspection from content-free state only. */
 var createPreparedProjectInspection = (input) => {
-	const { counts, formatVersion, items, maxEntries, maxRetainedBytes, resourceUsage: validationUsage, source, summary, valid } = input;
+	const { counts, formatVersion, items, maxEntries, preparedBytes, resourceUsage: validationUsage, source, summary, valid } = input;
 	const views = createViews(items);
-	const inspectionDigest = createIdentity([serializeDeterministically({
-		counts,
-		formatVersion,
-		itemKeys: items.map(({ key }) => key),
-		summary,
-		valid
-	})]);
-	const preparedBytes = calculatePreparedBytes(items, views, {
-		counts,
-		formatVersion,
-		inspectionDigest,
-		source,
-		summary,
-		valid
-	}, validationUsage.retainedBytes, maxRetainedBytes);
+	const inspectionDigest = createInspectionDigest(counts, formatVersion, items, summary, valid);
 	const resourceUsage = freezeRecursively({
 		canonicalBytes: validationUsage.canonicalBytes,
 		peakRetainedBytes: Math.max(validationUsage.peakRetainedBytes, validationUsage.retainedBytes + preparedBytes),
@@ -5150,42 +5194,24 @@ var createPreparedProjectInspection = (input) => {
 /** Prepares one immutable content-free inspection for synchronous bounded page reads. */
 var createProjectInspection = async (input, options) => {
 	const state = await validateProjectState(input, options);
-	const metadata = state.project === null ? [] : collectProjectMetadata(state.project);
-	const agentAssignments = state.project === null ? [] : collectProjectAgentAssignments(state.project);
-	const items = freezeRecursively(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"
-		}))
-	]));
+	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,
+		mirrors: state.result.summary?.counts.mirrors ?? 0,
+		runtimes: state.result.summary?.counts.runtimes ?? 0,
+		unresolved: state.result.summary?.counts.unresolved ?? 0
+	}, options.limits.maxRetainedBytes);
+	const counts = freezeRecursively(estimate.counts);
+	const items = freezeRecursively(createKeyedItems(iterateProjectInspectionItems(state)));
 	return createPreparedProjectInspection({
-		counts: freezeRecursively({
-			agents: state.result.summary?.counts.agents ?? 0,
-			context: state.result.summary?.counts.context ?? 0,
-			decisions: state.result.summary?.counts.decisions ?? 0,
-			diagnostics: state.result.diagnostics.length,
-			evidence: state.result.evidence.length,
-			metadata: metadata.length,
-			mirrors: state.result.summary?.counts.mirrors ?? 0,
-			runtimes: state.result.summary?.counts.runtimes ?? 0,
-			unresolved: state.result.summary?.counts.unresolved ?? 0
-		}),
+		counts,
 		formatVersion: state.result.formatVersion,
 		items,
 		maxEntries: options.limits.maxEntries,
-		maxRetainedBytes: options.limits.maxRetainedBytes,
+		preparedBytes: estimate.preparedBytes,
 		resourceUsage: state.resourceUsage,
 		source: state.result.source,
 		summary: state.result.summary,