rea-agents 1.7.0 → 2.1.0

package/dist/dotnet/ManagedMetadataInventory.js

@@ -0,0 +1,104 @@
+import { METADATA_TABLE_NAMES, } from "./ManagedMetadataLayout.js";
+import { readAssembly, readAssemblyReference, readCustomAttribute, readModule, readResource, } from "./ManagedMetadataInventoryRows.js";
+import { metadataToken } from "./ManagedMetadataHeaps.js";
+import { ManagedReaderFailure } from "./ManagedReaderFailure.js";
+const safeRead = (operation, issues) => {
+    try {
+        return operation();
+    }
+    catch (cause) {
+        if (!(cause instanceof ManagedReaderFailure))
+            throw cause;
+        issues.push(cause.issue);
+        return undefined;
+    }
+};
+const pageRows = (descriptor, offset, limit, read) => {
+    const total = descriptor?.rowCount ?? 0;
+    const items = [];
+    const end = Math.min(total, offset + limit);
+    for (let index = offset; index < end; index += 1) {
+        const item = read(index + 1);
+        if (item !== undefined)
+            items.push(item);
+    }
+    return {
+        items,
+        offset,
+        limit,
+        total,
+        returned: items.length,
+        dropped: total - items.length,
+        complete: offset === 0 && end === total && items.length === total,
+    };
+};
+const uniqueIssues = (issues) => [
+    ...new Map(issues.map((issue) => [JSON.stringify(issue), issue])).values(),
+];
+const readPagedReferences = (bytes, layout, input, issues) => pageRows(layout.table(35), input.referenceOffset, input.referenceLimit, (row) => safeRead(() => readAssemblyReference(bytes, layout, row, input.maxHeapItemBytes), issues));
+const readPagedResources = ({ bytes, layout, input, resourceDirectory, issues, }) => pageRows(layout.table(40), input.resourceOffset, input.resourceLimit, (row) => safeRead(() => readResource({
+    bytes,
+    layout,
+    row,
+    maxBytes: input.maxHeapItemBytes,
+    directory: resourceDirectory,
+    issues,
+}), issues));
+const readPagedAttributes = (bytes, layout, input, issues) => pageRows(layout.table(12), input.attributeOffset, input.attributeLimit, (row) => safeRead(() => readCustomAttribute(bytes, layout, row, input.maxHeapItemBytes), issues));
+const collectReferenceNames = (bytes, layout, maxBytes, issues) => {
+    const names = [];
+    const referenceTable = layout.table(35);
+    for (let row = 1; row <= (referenceTable?.rowCount ?? 0); row += 1) {
+        const reference = safeRead(() => readAssemblyReference(bytes, layout, row, maxBytes), issues);
+        if (reference !== undefined)
+            names.push(reference.name);
+    }
+    return names;
+};
+const collectTargetFrameworks = (bytes, layout, maxBytes, issues) => {
+    const targetFrameworks = [];
+    const attributeTable = layout.table(12);
+    for (let row = 1; row <= (attributeTable?.rowCount ?? 0); row += 1) {
+        const attribute = safeRead(() => readCustomAttribute(bytes, layout, row, maxBytes), issues);
+        if (attribute?.parent_token === metadataToken(32, 1) &&
+            attribute.type_name ===
+                "System.Runtime.Versioning.TargetFrameworkAttribute" &&
+            attribute.decoded_fixed_string !== null &&
+            !targetFrameworks.includes(attribute.decoded_fixed_string))
+            targetFrameworks.push(attribute.decoded_fixed_string);
+    }
+    return targetFrameworks;
+};
+/** Inventory bounded identity tables without CLR reflection or execution. */
+export const readManagedMetadataInventory = (bytes, layout, input, resourceDirectory) => {
+    const issues = [];
+    const module = safeRead(() => readModule(bytes, layout, input.maxHeapItemBytes), issues) ??
+        null;
+    const assembly = safeRead(() => readAssembly(bytes, layout, input.maxHeapItemBytes), issues) ?? null;
+    const references = readPagedReferences(bytes, layout, input, issues);
+    const resources = readPagedResources({
+        bytes,
+        layout,
+        input,
+        resourceDirectory,
+        issues,
+    });
+    const attributes = readPagedAttributes(bytes, layout, input, issues);
+    const referenceNames = collectReferenceNames(bytes, layout, input.maxHeapItemBytes, issues);
+    const targetFrameworks = collectTargetFrameworks(bytes, layout, input.maxHeapItemBytes, issues);
+    return {
+        module,
+        assembly,
+        targetFrameworks: [...targetFrameworks].sort(),
+        referenceNames: [...new Set(referenceNames)].sort(),
+        references,
+        resources,
+        attributes,
+        issues: uniqueIssues(issues),
+    };
+};
+/** Stable table-name/count projection for caller-visible coverage. */
+export const managedTableRowCounts = (layout) => Object.fromEntries([...layout.tables.values()].map(({ index, rowCount }) => [
+    METADATA_TABLE_NAMES[index] ?? `Table${String(index)}`,
+    rowCount,
+]));

package/dist/dotnet/ManagedMetadataInventoryRows.js

@@ -0,0 +1,292 @@
+import { metadataRowOffset, } from "./ManagedMetadataLayout.js";
+import { MetadataRowCursor, metadataToken, readMetadataBlob, readMetadataGuid, readMetadataString, sha256Bytes, strongNameToken, } from "./ManagedMetadataHeaps.js";
+import { managedFailure } from "./ManagedReaderFailure.js";
+const rowCursor = ({ bytes, layout, table, row, }) => {
+    const descriptor = layout.table(table);
+    const start = metadataRowOffset(layout, table, row);
+    if (descriptor === undefined)
+        throw managedFailure("invalid-row", `metadata.${String(table)}`, "Metadata table is absent", start);
+    return new MetadataRowCursor(bytes, start, start + descriptor.rowSize, `metadata.${descriptor.name}`);
+};
+const publicKeyIdentity = (bytes, kind) => ({
+    kind: bytes.length === 0 ? "none" : kind,
+    byte_length: bytes.length,
+    sha256: bytes.length === 0 ? null : sha256Bytes(bytes),
+    token: bytes.length === 0
+        ? null
+        : kind === "public-key"
+            ? strongNameToken(bytes)
+            : bytes.length === 8
+                ? bytes.toString("hex")
+                : null,
+});
+export const readModule = (bytes, layout, maxBytes) => {
+    const table = layout.table(0);
+    if (table === undefined || table.rowCount === 0)
+        return null;
+    const cursor = rowCursor({ bytes, layout, table: 0, row: 1 });
+    const generation = cursor.readUInt16();
+    const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    const mvid = readMetadataGuid(bytes, layout, cursor.readIndex(layout.guidIndexSize));
+    const encId = readMetadataGuid(bytes, layout, cursor.readIndex(layout.guidIndexSize));
+    const encBaseId = readMetadataGuid(bytes, layout, cursor.readIndex(layout.guidIndexSize));
+    return {
+        name,
+        generation,
+        mvid,
+        enc_id: encId,
+        enc_base_id: encBaseId,
+        token: metadataToken(0, 1),
+        row_offset: table.offset,
+    };
+};
+export const readAssembly = (bytes, layout, maxBytes) => {
+    const table = layout.table(32);
+    if (table === undefined || table.rowCount === 0)
+        return null;
+    const cursor = rowCursor({ bytes, layout, table: 32, row: 1 });
+    const hashAlgorithm = cursor.readUInt32();
+    const version = [
+        cursor.readUInt16(),
+        cursor.readUInt16(),
+        cursor.readUInt16(),
+        cursor.readUInt16(),
+    ].join(".");
+    const flags = cursor.readUInt32();
+    const key = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), maxBytes);
+    const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    const culture = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    return {
+        name,
+        version,
+        culture: culture.length === 0 ? null : culture,
+        flags,
+        hash_algorithm: hashAlgorithm,
+        public_key: publicKeyIdentity(key, (flags & 1) === 0 ? "public-key-token" : "public-key"),
+        token: metadataToken(32, 1),
+        row_offset: table.offset,
+    };
+};
+export const readAssemblyReference = (bytes, layout, row, maxBytes) => {
+    const cursor = rowCursor({ bytes, layout, table: 35, row });
+    const version = [
+        cursor.readUInt16(),
+        cursor.readUInt16(),
+        cursor.readUInt16(),
+        cursor.readUInt16(),
+    ].join(".");
+    const flags = cursor.readUInt32();
+    const keyOrToken = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), maxBytes);
+    const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    const culture = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    const hashValue = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), maxBytes);
+    return {
+        name,
+        version,
+        culture: culture.length === 0 ? null : culture,
+        flags,
+        public_key_or_token: publicKeyIdentity(keyOrToken, (flags & 1) === 0 ? "public-key-token" : "public-key"),
+        hash_value_sha256: hashValue.length === 0 ? null : sha256Bytes(hashValue),
+        hash_value_length: hashValue.length,
+        token: metadataToken(35, row),
+        row_offset: metadataRowOffset(layout, 35, row),
+    };
+};
+const codedToken = (raw, bits, tables) => {
+    if (raw === 0)
+        return null;
+    const tag = raw & (2 ** bits - 1);
+    const row = Math.floor(raw / 2 ** bits);
+    const table = tables[tag];
+    return table === undefined || row === 0 ? null : metadataToken(table, row);
+};
+const readTypeName = ({ bytes, layout, table, row, maxBytes, }) => {
+    const descriptor = layout.table(table);
+    if (descriptor === undefined || row < 1 || row > descriptor.rowCount)
+        return null;
+    const cursor = rowCursor({ bytes, layout, table, row });
+    if (table === 1)
+        cursor.readIndex(layout.codedIndexSize("ResolutionScope"));
+    else
+        cursor.readUInt32();
+    const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    const namespace = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    return namespace.length === 0 ? name : `${namespace}.${name}`;
+};
+const declaringTypeForMethod = (bytes, layout, methodRow, maxBytes) => {
+    const types = layout.table(2);
+    const methods = layout.table(6);
+    if (types === undefined || methods === undefined)
+        return null;
+    for (let row = 1; row <= types.rowCount; row += 1) {
+        const cursor = rowCursor({ bytes, layout, table: 2, row });
+        cursor.readUInt32();
+        const nameIndex = cursor.readIndex(layout.stringIndexSize);
+        const namespaceIndex = cursor.readIndex(layout.stringIndexSize);
+        cursor.readIndex(layout.codedIndexSize("TypeDefOrRef"));
+        cursor.readIndex(layout.tableIndexSize(4));
+        const methodStart = cursor.readIndex(layout.tableIndexSize(6));
+        const methodEnd = row === types.rowCount
+            ? methods.rowCount + 1
+            : methodListForType(bytes, layout, row + 1);
+        if (methodRow < methodStart || methodRow >= methodEnd)
+            continue;
+        const name = readMetadataString(bytes, layout, nameIndex, maxBytes);
+        const namespace = readMetadataString(bytes, layout, namespaceIndex, maxBytes);
+        return namespace.length === 0 ? name : `${namespace}.${name}`;
+    }
+    return null;
+};
+const methodListForType = (bytes, layout, row) => {
+    const cursor = rowCursor({ bytes, layout, table: 2, row });
+    cursor.readUInt32();
+    cursor.readIndex(layout.stringIndexSize);
+    cursor.readIndex(layout.stringIndexSize);
+    cursor.readIndex(layout.codedIndexSize("TypeDefOrRef"));
+    cursor.readIndex(layout.tableIndexSize(4));
+    return cursor.readIndex(layout.tableIndexSize(6));
+};
+const attributeTypeName = (bytes, layout, rawType, maxBytes) => {
+    const tag = rawType & 7;
+    const row = Math.floor(rawType / 8);
+    if (row === 0)
+        return null;
+    if (tag === 2)
+        return declaringTypeForMethod(bytes, layout, row, maxBytes);
+    if (tag !== 3)
+        return null;
+    const memberRefs = layout.table(10);
+    if (memberRefs === undefined || row > memberRefs.rowCount)
+        return null;
+    const cursor = rowCursor({ bytes, layout, table: 10, row });
+    const parent = cursor.readIndex(layout.codedIndexSize("MemberRefParent"));
+    const parentTag = parent & 7;
+    const parentRow = Math.floor(parent / 8);
+    if (parentTag === 0)
+        return readTypeName({ bytes, layout, table: 2, row: parentRow, maxBytes });
+    if (parentTag === 1)
+        return readTypeName({ bytes, layout, table: 1, row: parentRow, maxBytes });
+    if (parentTag === 3)
+        return declaringTypeForMethod(bytes, layout, parentRow, maxBytes);
+    return null;
+};
+const decodeCompressedLength = (blob, offset) => {
+    const first = blob[offset];
+    if (first === undefined)
+        return undefined;
+    if ((first & 0x80) === 0)
+        return { length: first, prefix: 1 };
+    if ((first & 0xc0) === 0x80 && blob[offset + 1] !== undefined)
+        return {
+            length: ((first & 0x3f) << 8) | (blob[offset + 1] ?? 0),
+            prefix: 2,
+        };
+    if ((first & 0xe0) === 0xc0 &&
+        blob[offset + 1] !== undefined &&
+        blob[offset + 2] !== undefined &&
+        blob[offset + 3] !== undefined)
+        return {
+            length: (first & 0x1f) * 0x01_00_00_00 +
+                (blob[offset + 1] ?? 0) * 0x01_00_00 +
+                (blob[offset + 2] ?? 0) * 0x0100 +
+                (blob[offset + 3] ?? 0),
+            prefix: 4,
+        };
+    return undefined;
+};
+const decodeFixedString = (blob) => {
+    if (blob.length < 3 || blob.readUInt16LE(0) !== 1 || blob[2] === 0xff)
+        return null;
+    const length = decodeCompressedLength(blob, 2);
+    if (length === undefined)
+        return null;
+    const start = 2 + length.prefix;
+    if (start > blob.length - length.length)
+        return null;
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(blob.subarray(start, start + length.length));
+    }
+    catch {
+        return null;
+    }
+};
+export const readCustomAttribute = (bytes, layout, row, maxBytes) => {
+    const cursor = rowCursor({ bytes, layout, table: 12, row });
+    const parentRaw = cursor.readIndex(layout.codedIndexSize("HasCustomAttribute"));
+    const typeRaw = cursor.readIndex(layout.codedIndexSize("CustomAttributeType"));
+    const value = readMetadataBlob(bytes, layout, cursor.readIndex(layout.blobIndexSize), maxBytes);
+    const parent = codedToken(parentRaw, 5, [
+        6, 4, 1, 2, 8, 9, 10, 0, 14, 23, 20, 17, 26, 27, 32, 35, 38, 39, 40, 42,
+        44, 43,
+    ]);
+    if (parent === null)
+        throw managedFailure("invalid-row", "metadata.CustomAttribute", "CustomAttribute parent coded index is invalid", cursor.start);
+    const typeName = attributeTypeName(bytes, layout, typeRaw, maxBytes);
+    return {
+        parent_token: parent,
+        constructor_token: codedToken(typeRaw, 3, [undefined, undefined, 6, 10]),
+        type_name: typeName,
+        value_length: value.length,
+        value_sha256: sha256Bytes(value),
+        decoded_fixed_string: typeName === "System.Runtime.Versioning.TargetFrameworkAttribute"
+            ? decodeFixedString(value)
+            : null,
+        token: metadataToken(12, row),
+        row_offset: cursor.start,
+    };
+};
+export const readResource = ({ bytes, layout, row, maxBytes, directory, issues, }) => {
+    const cursor = rowCursor({ bytes, layout, table: 40, row });
+    const declaredOffset = cursor.readUInt32();
+    const flags = cursor.readUInt32();
+    const name = readMetadataString(bytes, layout, cursor.readIndex(layout.stringIndexSize), maxBytes);
+    const implementationRaw = cursor.readIndex(layout.codedIndexSize("Implementation"));
+    const implementationToken = codedToken(implementationRaw, 2, [38, 35, 39]);
+    let dataLength = null;
+    let dataSha256 = null;
+    if (implementationRaw === 0) {
+        if (directory === null || declaredOffset > directory.size - 4) {
+            issues.push({
+                code: "invalid-resource",
+                scope: `metadata.ManifestResource:${metadataToken(40, row)}`,
+                offset: directory?.offset ?? null,
+                detail: "Embedded resource offset leaves the CLI resources directory",
+            });
+        }
+        else {
+            const start = directory.offset + declaredOffset;
+            dataLength = bytes.readUInt32LE(start);
+            if (dataLength > directory.size - declaredOffset - 4) {
+                issues.push({
+                    code: "invalid-resource",
+                    scope: `metadata.ManifestResource:${metadataToken(40, row)}`,
+                    offset: start,
+                    detail: "Embedded resource length leaves the CLI resources directory",
+                });
+            }
+            else if (dataLength > maxBytes) {
+                issues.push({
+                    code: "limit-exceeded",
+                    scope: `metadata.ManifestResource:${metadataToken(40, row)}`,
+                    offset: start + 4,
+                    detail: `Embedded resource exceeds max_heap_item_bytes ${String(maxBytes)}; digest omitted`,
+                });
+            }
+            else {
+                dataSha256 = sha256Bytes(bytes.subarray(start + 4, start + 4 + dataLength));
+            }
+        }
+    }
+    return {
+        name,
+        flags,
+        visibility: (flags & 7) === 1 ? "public" : (flags & 7) === 2 ? "private" : "unknown",
+        implementation_token: implementationToken,
+        embedded: implementationRaw === 0,
+        declared_offset: declaredOffset,
+        data_length: dataLength,
+        data_sha256: dataSha256,
+        token: metadataToken(40, row),
+        row_offset: cursor.start,
+    };
+};

package/dist/dotnet/ManagedMetadataLayout.js

@@ -0,0 +1,259 @@
+import { managedFailure } from "./ManagedReaderFailure.js";
+import { computeRowSize, } from "./ManagedMetadataRowSizes.js";
+export const METADATA_TABLE_NAMES = [
+    "Module",
+    "TypeRef",
+    "TypeDef",
+    "FieldPtr",
+    "Field",
+    "MethodPtr",
+    "MethodDef",
+    "ParamPtr",
+    "Param",
+    "InterfaceImpl",
+    "MemberRef",
+    "Constant",
+    "CustomAttribute",
+    "FieldMarshal",
+    "DeclSecurity",
+    "ClassLayout",
+    "FieldLayout",
+    "StandAloneSig",
+    "EventMap",
+    "EventPtr",
+    "Event",
+    "PropertyMap",
+    "PropertyPtr",
+    "Property",
+    "MethodSemantics",
+    "MethodImpl",
+    "ModuleRef",
+    "TypeSpec",
+    "ImplMap",
+    "FieldRVA",
+    "ENCLog",
+    "ENCMap",
+    "Assembly",
+    "AssemblyProcessor",
+    "AssemblyOS",
+    "AssemblyRef",
+    "AssemblyRefProcessor",
+    "AssemblyRefOS",
+    "File",
+    "ExportedType",
+    "ManifestResource",
+    "NestedClass",
+    "GenericParam",
+    "MethodSpec",
+    "GenericParamConstraint",
+];
+const CODED_INDEXES = {
+    TypeDefOrRef: { bits: 2, tables: [2, 1, 27] },
+    HasConstant: { bits: 2, tables: [4, 8, 23] },
+    HasCustomAttribute: {
+        bits: 5,
+        tables: [
+            6, 4, 1, 2, 8, 9, 10, 0, 14, 23, 20, 17, 26, 27, 32, 35, 38, 39, 40, 42,
+            44, 43,
+        ],
+    },
+    HasFieldMarshal: { bits: 1, tables: [4, 8] },
+    HasDeclSecurity: { bits: 2, tables: [2, 6, 32] },
+    MemberRefParent: { bits: 3, tables: [2, 1, 26, 6, 27] },
+    HasSemantics: { bits: 1, tables: [20, 23] },
+    MethodDefOrRef: { bits: 1, tables: [6, 10] },
+    MemberForwarded: { bits: 1, tables: [4, 6] },
+    Implementation: { bits: 2, tables: [38, 35, 39] },
+    CustomAttributeType: { bits: 3, tables: [6, 10] },
+    ResolutionScope: { bits: 2, tables: [0, 26, 35, 1] },
+    TypeOrMethodDef: { bits: 1, tables: [2, 6] },
+};
+const SUPPORTED_TABLE_MASK = (1n << BigInt(METADATA_TABLE_NAMES.length)) - 1n;
+const requireRange = (bytes, offset, length, scope) => {
+    if (!Number.isSafeInteger(offset) ||
+        !Number.isSafeInteger(length) ||
+        offset < 0 ||
+        length < 0 ||
+        offset > bytes.length - length)
+        throw managedFailure("invalid-metadata-root", scope, `${scope} leaves the metadata byte range`, Number.isSafeInteger(offset) && offset >= 0 ? offset : null);
+};
+const align4 = (value) => (value + 3) & ~3;
+const readStreamName = (bytes, offset) => {
+    const endLimit = Math.min(bytes.length, offset + 32);
+    let end = offset;
+    while (end < endLimit && bytes[end] !== 0)
+        end += 1;
+    if (end === endLimit)
+        throw managedFailure("invalid-stream", "metadata.stream-name", "Metadata stream name is missing a bounded terminator", offset);
+    const nameBytes = bytes.subarray(offset, end);
+    if (nameBytes.some((byte) => byte < 0x20 || byte > 0x7e))
+        throw managedFailure("invalid-stream", "metadata.stream-name", "Metadata stream name is not printable ASCII", offset);
+    return {
+        name: nameBytes.toString("ascii"),
+        next: align4(end + 1),
+    };
+};
+const streamByName = (streams, names) => {
+    for (const name of names) {
+        const stream = streams.get(name);
+        if (stream !== undefined)
+            return stream;
+    }
+    return undefined;
+};
+const requireStream = (streams, name) => {
+    const stream = streams.get(name);
+    if (stream === undefined)
+        throw managedFailure("missing-stream", `metadata.${name}`, `Required metadata stream ${name} is absent`);
+    return stream;
+};
+const codedSize = (name, rowCounts) => {
+    const descriptor = CODED_INDEXES[name];
+    let maximum = 0;
+    for (const table of descriptor.tables)
+        maximum = Math.max(maximum, rowCounts[table] ?? 0);
+    return maximum < 2 ** (16 - descriptor.bits) ? 2 : 4;
+};
+const tableSize = (index, rows) => (rows[index] ?? 0) < 0x1_0000 ? 2 : 4;
+const readMetadataStreams = (bytes, rootOffset) => {
+    if (bytes.readUInt32LE(0) !== 0x424a_5342)
+        throw managedFailure("invalid-metadata-root", "metadata.signature", "CLI metadata signature is not BSJB", rootOffset);
+    const versionLength = bytes.readUInt32LE(12);
+    requireRange(bytes, 16, versionLength, "metadata.version");
+    const versionBytes = bytes.subarray(16, 16 + versionLength);
+    const zero = versionBytes.indexOf(0);
+    const version = versionBytes
+        .subarray(0, zero < 0 ? versionBytes.length : zero)
+        .toString("utf8");
+    let cursor = align4(16 + versionLength);
+    requireRange(bytes, cursor, 4, "metadata.stream-count");
+    const streamCount = bytes.readUInt16LE(cursor + 2);
+    if (streamCount === 0 || streamCount > 64)
+        throw managedFailure("invalid-stream", "metadata.stream-count", "Metadata stream count is outside the admitted range", rootOffset + cursor + 2);
+    cursor += 4;
+    const streams = new Map();
+    for (let index = 0; index < streamCount; index += 1) {
+        requireRange(bytes, cursor, 8, "metadata.stream-header");
+        const relativeOffset = bytes.readUInt32LE(cursor);
+        const streamSize = bytes.readUInt32LE(cursor + 4);
+        const named = readStreamName(bytes, cursor + 8);
+        if (streams.has(named.name))
+            throw managedFailure("invalid-stream", "metadata.stream-header", `Duplicate metadata stream ${named.name}`, rootOffset + cursor);
+        requireRange(bytes, relativeOffset, streamSize, `metadata.${named.name}`);
+        streams.set(named.name, {
+            name: named.name,
+            offset: rootOffset + relativeOffset,
+            size: streamSize,
+        });
+        cursor = named.next;
+    }
+    return { streams, version };
+};
+const readTablesHeader = (bytes, streams) => {
+    const tablesStream = streamByName(streams, ["#~", "#-"]);
+    if (tablesStream === undefined)
+        throw managedFailure("missing-stream", "metadata.tables", "Required metadata table stream #~ or #- is absent");
+    const tableBytes = bytes.subarray(tablesStream.offset, tablesStream.offset + tablesStream.size);
+    requireRange(tableBytes, 0, 24, "metadata.tables-header");
+    const heapSizes = tableBytes[6] ?? 0;
+    const heaps = {
+        string: (heapSizes & 0x01) === 0 ? 2 : 4,
+        guid: (heapSizes & 0x02) === 0 ? 2 : 4,
+        blob: (heapSizes & 0x04) === 0 ? 2 : 4,
+    };
+    const valid = tableBytes.readBigUInt64LE(8);
+    if ((valid & ~SUPPORTED_TABLE_MASK) !== 0n)
+        throw managedFailure("invalid-tables", "metadata.valid-mask", "Metadata valid mask names unsupported tables outside the admitted ECMA-335 range", tablesStream.offset + 8);
+    return { tableBytes, tablesOffset: tablesStream.offset, heaps, valid };
+};
+const readRowCounts = (tableBytes, valid, maxTableRows, tablesOffset) => {
+    const rowCounts = Array(METADATA_TABLE_NAMES.length).fill(0);
+    let tableCursor = 24;
+    for (let index = 0; index < METADATA_TABLE_NAMES.length; index += 1) {
+        if ((valid & (1n << BigInt(index))) === 0n)
+            continue;
+        requireRange(tableBytes, tableCursor, 4, "metadata.table-row-count");
+        const count = tableBytes.readUInt32LE(tableCursor);
+        if (count > maxTableRows)
+            throw managedFailure("limit-exceeded", `metadata.${METADATA_TABLE_NAMES[index] ?? String(index)}`, `Metadata table row count ${String(count)} exceeds max_table_rows ${String(maxTableRows)}`, tablesOffset + tableCursor);
+        rowCounts[index] = count;
+        tableCursor += 4;
+    }
+    return rowCounts;
+};
+const buildRowSizeContext = (rowCounts, heaps) => ({
+    tableSize: (index) => tableSize(index, rowCounts),
+    codedSize: (name) => codedSize(name, rowCounts),
+    stringSize: heaps.string,
+    guidSize: heaps.guid,
+    blobSize: heaps.blob,
+});
+const buildMetadataTables = ({ tableBytes, rowCounts, heaps, valid, tablesOffset, }) => {
+    const tables = new Map();
+    const context = buildRowSizeContext(rowCounts, heaps);
+    let tableCursor = 24;
+    for (let index = 0; index < METADATA_TABLE_NAMES.length; index += 1) {
+        if ((valid & (1n << BigInt(index))) === 0n)
+            continue;
+        tableCursor += 4;
+    }
+    for (let index = 0; index < METADATA_TABLE_NAMES.length; index += 1) {
+        const count = rowCounts[index] ?? 0;
+        if ((valid & (1n << BigInt(index))) === 0n)
+            continue;
+        const sizeOfRow = computeRowSize(index, context);
+        const byteLength = count * sizeOfRow;
+        if (!Number.isSafeInteger(byteLength))
+            throw managedFailure("invalid-tables", "metadata.tables", "Metadata table byte size overflowed", tablesOffset + tableCursor);
+        requireRange(tableBytes, tableCursor, byteLength, "metadata.table-data");
+        tables.set(index, {
+            index,
+            name: METADATA_TABLE_NAMES[index] ?? `Table${String(index)}`,
+            rowCount: count,
+            rowSize: sizeOfRow,
+            offset: tablesOffset + tableCursor,
+        });
+        tableCursor += byteLength;
+    }
+    return tables;
+};
+/** Parse ECMA-335 stream and table layout with checked byte extents. */
+export const readManagedMetadataLayout = (artifact, rootOffset, size, maxTableRows) => {
+    if (size < 20 || rootOffset < 0 || rootOffset > artifact.length - size)
+        throw managedFailure("invalid-metadata-root", "metadata.root", "CLI metadata directory leaves the artifact byte range", rootOffset);
+    const bytes = artifact.subarray(rootOffset, rootOffset + size);
+    const { streams, version } = readMetadataStreams(bytes, rootOffset);
+    const { tableBytes, tablesOffset, heaps, valid } = readTablesHeader(artifact, streams);
+    const rowCounts = readRowCounts(tableBytes, valid, maxTableRows, tablesOffset);
+    const tables = buildMetadataTables({
+        tableBytes,
+        rowCounts,
+        heaps,
+        valid,
+        tablesOffset,
+    });
+    return {
+        rootOffset,
+        size,
+        version,
+        streamNames: [...streams.keys()].sort(),
+        strings: requireStream(streams, "#Strings"),
+        guid: requireStream(streams, "#GUID"),
+        blob: requireStream(streams, "#Blob"),
+        tables,
+        rowCounts,
+        stringIndexSize: heaps.string,
+        guidIndexSize: heaps.guid,
+        blobIndexSize: heaps.blob,
+        table: (index) => tables.get(index),
+        tableIndexSize: (index) => tableSize(index, rowCounts),
+        codedIndexSize: (name) => codedSize(name, rowCounts),
+    };
+};
+/** Resolve a one-based metadata row to its exact file offset. */
+export const metadataRowOffset = (layout, table, row) => {
+    const descriptor = layout.table(table);
+    if (descriptor === undefined || row < 1 || row > descriptor.rowCount)
+        throw managedFailure("invalid-row", `metadata.${METADATA_TABLE_NAMES[table] ?? String(table)}`, `Metadata row ${String(row)} is outside its table`);
+    return descriptor.offset + (row - 1) * descriptor.rowSize;
+};