diff --git a/docs/model-artifacts.md b/docs/model-artifacts.md index a1a761190e..542d016577 100644 --- a/docs/model-artifacts.md +++ b/docs/model-artifacts.md @@ -257,6 +257,9 @@ The reader admits one active inspection per provider. It enforces a 100,000,000 byte header ceiling (safetensors counts its declared JSON bytes separately from the fixed eight-byte length prefix; GGUF counts the complete header) and a separate 32 MiB retained representation budget before retaining rows or expanding strings. +GGUF checks that a declared string leaves room for the minimum framing of +later metadata rows, tensor descriptors and array elements before charging +its representation budget. Numeric products use exact integer arithmetic. GGUF follows its four-dimensional tensor layout and limits metadata array nesting to 32 frames. Resource refusals are typed, rather than returned as complete empty inventories. Cancellation diff --git a/src/model/GgufHeader.ts b/src/model/GgufHeader.ts index dca81af9b6..0ad3377e34 100644 --- a/src/model/GgufHeader.ts +++ b/src/model/GgufHeader.ts @@ -35,7 +35,10 @@ const NAMES = [ "INT64", "FLOAT64", ] as const; -const WIDTHS = [1, 1, 2, 2, 4, 4, 4, 1, 8, 12, 8, 8, 8]; +const STRING_LENGTH_BYTES = 8; +const WIDTHS = [1, 1, 2, 2, 4, 4, 4, 1, STRING_LENGTH_BYTES, 12, 8, 8, 8]; +const MIN_METADATA_ROW_BYTES = STRING_LENGTH_BYTES + 4 + 1; +const MIN_TENSOR_DESCRIPTOR_BYTES = STRING_LENGTH_BYTES + 4 + 4 + 8; export interface GgufProgress { onHeader(info: { @@ -71,11 +74,15 @@ export class GgufHeader { return (await this.#field(width)).word(0, width === 4 ? 32 : 64); } - async #text(retain: boolean, maximum?: number): Promise { - const rawLength = await this.#unsigned(8); + async #text( + retain: boolean, + requiredAfter: number, + maximum?: number, + ): Promise { + const rawLength = await this.#unsigned(STRING_LENGTH_BYTES); if (maximum !== undefined && rawLength > BigInt(maximum)) rejectModel("GGUF name exceeds its format byte limit"); - this.reader.guarantee(rawLength); + this.reader.guarantee(rawLength + BigInt(requiredAfter)); const length = Number(rawLength); if (retain) this.#budget.charge(6 * length + 2); // Omitted preview entries still need validation, but not decoded strings. @@ -109,6 +116,7 @@ export class GgufHeader { async #value( type: number, retain: boolean, + requiredAfter: number, enclosingFrames = 0, ): Promise<{ value: JsonValue; @@ -116,11 +124,13 @@ export class GgufHeader { element_count: number | null; complete: boolean; }> { - if (NAMES[type] === undefined) + const width = WIDTHS[type]; + if (width === undefined) rejectModel(`Unknown GGUF metadata type ${String(type)}`); + this.reader.guarantee(width + requiredAfter); if (type === 8) return { - value: await this.#text(retain), + value: await this.#text(retain, requiredAfter), element_type: null, element_count: null, complete: true, @@ -139,7 +149,7 @@ export class GgufHeader { const minimum = WIDTHS[element]; if (minimum === undefined) rejectModel(`Unknown GGUF array element type ${String(element)}`); - this.reader.guarantee(rawCount * BigInt(minimum)); + this.reader.guarantee(rawCount * BigInt(minimum) + BigInt(requiredAfter)); const count = Number(rawCount); const preview: JsonValue[] = []; if (retain) @@ -147,7 +157,6 @@ export class GgufHeader { let complete = count <= MODEL_ARRAY_PREVIEW; for (let index = 0; index < count; index++) { if (index % 4096 === 4095) await setImmediate(); - this.reader.guarantee((count - index) * minimum); if ( element !== 8 && element !== 9 && @@ -164,7 +173,12 @@ export class GgufHeader { break; } const keep = retain && index < MODEL_ARRAY_PREVIEW; - const value = await this.#value(element, keep, frames); + const value = await this.#value( + element, + keep, + (count - index - 1) * minimum + requiredAfter, + frames, + ); if (keep) preview.push( element === 9 @@ -186,7 +200,7 @@ export class GgufHeader { complete, }; } - const b = await this.#field(WIDTHS[type] ?? 0); + const b = await this.#field(width); let value: JsonValue; switch (type) { case 0: @@ -273,7 +287,9 @@ export class GgufHeader { rejectModel("Big-endian GGUF requires version 3"); const rawTensorCount = await this.#unsigned(8); const rawMetadataCount = await this.#unsigned(8); - const minimumDirectoryBytes = rawTensorCount * 24n + rawMetadataCount * 13n; + const minimumDirectoryBytes = + rawTensorCount * BigInt(MIN_TENSOR_DESCRIPTOR_BYTES) + + rawMetadataCount * BigInt(MIN_METADATA_ROW_BYTES); this.reader.requireFileExtent(this.reader.position, minimumDirectoryBytes); const tensorCount = Number(rawTensorCount); const metadataCount = Number(rawMetadataCount); @@ -288,10 +304,16 @@ export class GgufHeader { const metadata: ModelMetadata[] = []; const keys = new Set(); let alignment = 32; + let remainingDirectoryBytes = Number(minimumDirectoryBytes); for (let index = 0; index < metadataCount; index++) { - this.reader.guarantee((metadataCount - index) * 13 + tensorCount * 24); + this.reader.guarantee(remainingDirectoryBytes); + remainingDirectoryBytes -= MIN_METADATA_ROW_BYTES; const start = this.reader.position; - const key = await this.#text(true, 65535); + const key = await this.#text( + true, + remainingDirectoryBytes + MIN_METADATA_ROW_BYTES - STRING_LENGTH_BYTES, + 65535, + ); // Numeric hierarchy components occur in standardized base_model.{id} keys. if ( !/^[a-z0-9]+(?:[_-][a-z0-9]+)*(?:\.[a-z0-9]+(?:[_-][a-z0-9]+)*)*$/u.test( @@ -304,7 +326,7 @@ export class GgufHeader { if (keys.has(key)) rejectModel(`Duplicate GGUF metadata key ${key}`); keys.add(key); const type = Number(await this.#unsigned(4)); - const parsed = await this.#value(type, true); + const parsed = await this.#value(type, true, remainingDirectoryBytes); const row = { index, key, @@ -345,9 +367,16 @@ export class GgufHeader { progress?.onLimitation(message); }; for (let index = 0; index < tensorCount; index++) { - this.reader.guarantee((tensorCount - index) * 24); + this.reader.guarantee(remainingDirectoryBytes); + remainingDirectoryBytes -= MIN_TENSOR_DESCRIPTOR_BYTES; const start = this.reader.position; - const name = await this.#text(true, 64); + const name = await this.#text( + true, + remainingDirectoryBytes + + MIN_TENSOR_DESCRIPTOR_BYTES - + STRING_LENGTH_BYTES, + 64, + ); if (names.has(name)) rejectModel(`Duplicate GGUF tensor name ${name}`); names.add(name); const dimensions = Number(await this.#unsigned(4)); diff --git a/tests/boundary/model/modelArtifact.test.ts b/tests/boundary/model/modelArtifact.test.ts index 1834d5352a..ed8eef82fc 100644 --- a/tests/boundary/model/modelArtifact.test.ts +++ b/tests/boundary/model/modelArtifact.test.ts @@ -1221,6 +1221,88 @@ it("retains GGUF representation capacity when declared string bytes can fit", as }); }); +it.each([ + "metadata row", + "tensor descriptor", + "array element", + "outer array sibling", +] as const)( + "checks required GGUF %s framing before charging a large string", + async (following) => { + const seed = ggufFixture({ tensors: [] }); + const largeStringBytes = 6_000_000; + const stringLength = seed.u64(BigInt(largeStringBytes)); + const twoStrings = Buffer.concat([seed.u32(8), seed.u64(2n)]); + const array = + following === "array element" || following === "outer array sibling"; + const outer = following === "outer array sibling"; + const prefix = ggufFixture({ + tensors: [], + metadata: [ + { + key: "custom.value", + type: array ? 9 : 8, + value: Buffer.concat([ + ...(outer ? [seed.u32(9), seed.u64(2n)] : []), + ...(array ? [twoStrings] : []), + stringLength, + ]), + }, + ], + }).header; + if (following === "metadata row") prefix.writeBigUInt64LE(2n, 16); + if (following === "tensor descriptor") prefix.writeBigUInt64LE(1n, 8); + const stringEnd = prefix.length + largeStringBytes; + const emptyString = seed.text(""); + const tail = { + "metadata row": Buffer.concat([ + seed.text("custom.tail"), + seed.u32(0), + Buffer.from([1]), + ]), + "tensor descriptor": Buffer.concat([ + seed.text("weight"), + seed.u32(1), + seed.u64(1n), + seed.u32(0), + seed.u64(0n), + ]), + "array element": emptyString, + "outer array sibling": Buffer.concat([ + emptyString, + seed.u32(8), + seed.u64(0n), + ]), + }[following]; + const { provider, path } = await providerAt(prefix); + const handle = await open(path, "r+"); + try { + // For nested arrays the immediate string sibling fits. Only the outer + // array's second element is missing, so its minimum must propagate. + if (outer) + await handle.write(emptyString, 0, emptyString.length, stringEnd); + else await handle.truncate(stringEnd); + const malformed = await provider.inspect({ path, hash: "header" }); + if (malformed.ok) throw new Error("Missing GGUF framing was accepted"); + expect.soft(malformed.error).toMatchObject(INVALID_FORMAT); + + await handle.write(tail, 0, tail.length, stringEnd); + if (following === "tensor descriptor") + await handle.truncate( + Math.ceil((stringEnd + tail.length) / 32) * 32 + 4, + ); + const limited = await provider.inspect({ path, hash: "header" }); + if (limited.ok) throw new Error("Oversized representation was accepted"); + expect(limited.error).toMatchObject({ + _tag: "AnalysisResourceConstraintError", + reportedLimits: { maximum_representation_bytes: MODEL_REPORT_BYTES }, + }); + } finally { + await handle.close(); + } + }, +); + it("retains GGUF representation capacity when the declared directory can fit", async () => { const header = Buffer.alloc(24); header.write("GGUF");