feat(model): inspect GGUF and safetensors declarations (#5603)

This commit is contained in:
gensokyo-dev authored and GitHub committed 2026-10-21 00:50:50 +08:00
1 parent 5b676ba9f3
commit 98f4072f1f
60 files changed
+3835 -3

No files matched your search

+363
View File
@@ -0,0 +1,363 @@
import { TextDecoder } from "node:util";
import { setImmediate } from "node:timers/promises";
import type { JsonValue } from "../domain/jsonValue.js";
import type {
ModelMetadata,
ModelTensor,
} from "../domain/model/modelArtifact.js";
import { ModelHeaderReader } from "./ModelHeaderReader.js";
import {
MODEL_ARRAY_PREVIEW,
ModelFormatFailure,
ModelReportBudget,
rejectModel,
} from "./ModelFormat.js";
import { ggmlType } from "./ModelTensorTypes.js";
const NAMES = [
"UINT8",
"INT8",
"UINT16",
"INT16",
"UINT32",
"INT32",
"FLOAT32",
"BOOL",
"STRING",
"ARRAY",
"UINT64",
"INT64",
"FLOAT64",
] as const;
const WIDTHS = [1, 1, 2, 2, 4, 4, 4, 1, 8, 12, 8, 8, 8];
/** Explicit-endian GGUF v2/v3 metadata and tensor-directory parser. */
export class GgufHeader {
#little = true;
readonly #budget = new ModelReportBudget();
constructor(readonly reader: ModelHeaderReader) {}
async #unsigned(width: 4 | 8): Promise<number> {
const b = await this.reader.take(width);
const value =
width === 4
? BigInt(this.#little ? b.readUInt32LE() : b.readUInt32BE())
: this.#little
? b.readBigUInt64LE()
: b.readBigUInt64BE();
if (value > BigInt(Number.MAX_SAFE_INTEGER))
throw new ModelFormatFailure(
"capacity",
"Header length/count exceeds exact host offset precision",
);
return Number(value);
}
async #text(retain: boolean, maximum?: number): Promise<string> {
const length = await this.#unsigned(8);
if (maximum !== undefined && length > maximum)
rejectModel("GGUF name exceeds its format byte limit");
if (retain) this.#budget.charge(6 * length + 2);
this.reader.guarantee(length);
const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
let result = "";
try {
for (let left = length; left > 0;) {
const n = Math.min(left, 65536);
const text = decoder.decode(await this.reader.take(n), {
stream: true,
});
if (retain) result += text;
left -= n;
}
const tail = decoder.decode();
if (retain) result += tail;
} catch (cause) {
if (cause instanceof TypeError)
rejectModel("GGUF string is not valid UTF-8");
throw cause;
}
return result;
}
async #value(
type: number,
retain: boolean,
depth = 0,
): Promise<{
value: JsonValue;
element_type: string | null;
element_count: number | null;
complete: boolean;
}> {
if (NAMES[type] === undefined)
rejectModel(`Unknown GGUF metadata type ${String(type)}`);
if (depth > 32)
throw new ModelFormatFailure(
"capacity",
"GGUF metadata nesting exceeds 32 array frames",
);
if (type === 8)
return {
value: await this.#text(retain),
element_type: null,
element_count: null,
complete: true,
};
if (type === 9) {
const element = await this.#unsigned(4);
const count = await this.#unsigned(8);
const minimum = WIDTHS[element];
if (minimum === undefined)
rejectModel(`Unknown GGUF array element type ${String(element)}`);
this.reader.guarantee(count * minimum);
const preview: JsonValue[] = [];
if (retain)
this.#budget.charge(128 + Math.min(count, MODEL_ARRAY_PREVIEW) * 64);
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 &&
(!retain || index >= MODEL_ARRAY_PREVIEW)
) {
let left = (count - index) * minimum;
while (left > 0) {
const size = Math.min(left, 65536);
const bytes = await this.reader.take(size);
if (element === 7 && bytes.some((byte) => byte !== 0 && byte !== 1))
rejectModel("GGUF boolean must be 0 or 1");
left -= size;
}
break;
}
const keep = retain && index < MODEL_ARRAY_PREVIEW;
const value = await this.#value(element, keep, depth + 1);
if (keep)
preview.push(
element === 9
? {
type: "ARRAY",
element_type: value.element_type,
element_count: value.element_count,
preview: value.value,
preview_complete: value.complete,
}
: value.value,
);
complete &&= value.complete;
}
return {
value: preview,
element_type: NAMES[element] ?? null,
element_count: count,
complete,
};
}
const b = await this.reader.take(WIDTHS[type] ?? 0);
let value: JsonValue;
switch (type) {
case 0:
value = b.readUInt8();
break;
case 1:
value = b.readInt8();
break;
case 2:
value = this.#little ? b.readUInt16LE() : b.readUInt16BE();
break;
case 3:
value = this.#little ? b.readInt16LE() : b.readInt16BE();
break;
case 4:
value = this.#little ? b.readUInt32LE() : b.readUInt32BE();
break;
case 5:
value = this.#little ? b.readInt32LE() : b.readInt32BE();
break;
case 6:
value = this.#little ? b.readFloatLE() : b.readFloatBE();
break;
case 7:
if (b[0] !== 0 && b[0] !== 1)
rejectModel("GGUF boolean must be 0 or 1");
value = b[0] === 1;
break;
case 10:
value = (
this.#little ? b.readBigUInt64LE() : b.readBigUInt64BE()
).toString();
break;
case 11:
value = (
this.#little ? b.readBigInt64LE() : b.readBigInt64BE()
).toString();
break;
case 12:
value = this.#little ? b.readDoubleLE() : b.readDoubleBE();
break;
default:
return rejectModel("Unsupported GGUF scalar");
}
if (Object.is(value, -0)) value = "-0";
if (typeof value === "number" && !Number.isFinite(value))
value = Number.isNaN(value)
? "NaN"
: value > 0
? "+Infinity"
: "-Infinity";
return {
value: retain ? value : null,
element_type: null,
element_count: null,
complete: true,
};
}
async read(): Promise<{
version: number;
byte_order: "little" | "big";
alignment: number;
tensor_data_offset: number;
metadata: ModelMetadata[];
tensors: ModelTensor[];
}> {
const versionBytes = await this.reader.take(4);
this.#little =
versionBytes.readUInt32LE() === 2 || versionBytes.readUInt32LE() === 3;
const version = this.#little
? versionBytes.readUInt32LE()
: versionBytes.readUInt32BE();
if (version !== 2 && version !== 3)
throw new ModelFormatFailure(
"unsupported",
`GGUF version ${String(version)} is unsupported; supported versions are 2 and 3`,
);
if (!this.#little && version !== 3)
rejectModel("Big-endian GGUF requires version 3");
const tensorCount = await this.#unsigned(8);
const metadataCount = await this.#unsigned(8);
this.#budget.charge((tensorCount + metadataCount) * 512);
this.reader.guarantee(tensorCount * 20 + metadataCount * 13);
const metadata: ModelMetadata[] = [];
const keys = new Set<string>();
let alignment = 32;
for (let index = 0; index < metadataCount; index++) {
this.reader.guarantee((metadataCount - index) * 13 + tensorCount * 20);
const start = this.reader.position;
const key = await this.#text(true, 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(key)
)
rejectModel(
"GGUF metadata keys require ASCII lower-snake-case hierarchy components",
);
if (keys.has(key)) rejectModel(`Duplicate GGUF metadata key ${key}`);
keys.add(key);
const type = await this.#unsigned(4);
const parsed = await this.#value(type, true);
metadata.push({
index,
key,
type: NAMES[type] ?? String(type),
value: parsed.value,
element_type: parsed.element_type,
element_count: parsed.element_count,
preview_complete: parsed.complete,
source_offset: start,
source_length: this.reader.position - start,
json_pointer: null,
});
if (key === "general.alignment") {
if (
type !== 4 ||
typeof parsed.value !== "number" ||
parsed.value === 0 ||
parsed.value % 8 !== 0
)
rejectModel(
"GGUF general.alignment must be a positive UINT32 multiple of eight",
);
alignment = parsed.value;
}
}
const tensors: ModelTensor[] = [];
const names = new Set<string>();
for (let index = 0; index < tensorCount; index++) {
this.reader.guarantee((tensorCount - index) * 20);
const start = this.reader.position;
const name = await this.#text(true, 64);
if (names.has(name)) rejectModel(`Duplicate GGUF tensor name ${name}`);
names.add(name);
const dimensions = await this.#unsigned(4);
if (dimensions > 4)
rejectModel("GGUF tensor dimension count must be at most 4");
const shape: string[] = [];
let parameters = 1n;
for (let d = 0; d < dimensions; d++) {
const b = await this.reader.take(8);
const value = this.#little ? b.readBigUInt64LE() : b.readBigUInt64BE();
shape.push(value.toString());
parameters *= value;
}
const id = await this.#unsigned(4);
const offset = await this.#unsigned(8);
if (offset % alignment !== 0)
rejectModel(`GGUF tensor ${name} offset is not aligned`);
const type = ggmlType(id);
let length: number | null = null;
if (type !== undefined) {
if (BigInt(shape[0] ?? "1") % BigInt(type[1]) !== 0n)
rejectModel(
`GGUF tensor ${name} first dimension is not divisible by the quantization block size`,
);
const bytes = (parameters / BigInt(type[1])) * BigInt(type[2]);
if (bytes > BigInt(this.reader.size))
rejectModel(
`GGUF tensor ${name} declared byte length exceeds the file`,
);
length = Number(bytes);
}
tensors.push({
index,
name,
type: type?.[0] ?? `UNKNOWN_${String(id)}`,
type_id: id,
shape,
data_offset: offset,
file_offset: 0,
byte_length: length,
parameter_count: parameters.toString(),
byte_length_state: length === null ? "unknown" : "derived",
storage_validation: length === null ? "unknown" : "consistent",
source_offset: start,
source_length: this.reader.position - start,
json_pointer: null,
});
}
const tensor_data_offset =
tensorCount === 0
? this.reader.position
: Math.ceil(this.reader.position / alignment) * alignment;
for (const tensor of tensors) {
const offset = BigInt(tensor_data_offset) + BigInt(tensor.data_offset);
if (
offset > BigInt(this.reader.size) ||
offset + BigInt(tensor.byte_length ?? 0) > BigInt(this.reader.size)
)
rejectModel(`GGUF tensor ${tensor.name} range is outside the file`);
tensor.file_offset = Number(offset);
}
return {
version,
byte_order: this.#little ? "little" : "big",
alignment,
tensor_data_offset,
metadata,
tensors,
};
}
}
+378
View File
@@ -0,0 +1,378 @@
import { lstat, type FileHandle } from "node:fs/promises";
import type { ModelArtifactPort } from "../application/model/ModelArtifactPort.js";
import { createModelArtifactEvidence } from "../application/model/ModelArtifactEvidence.js";
import type { ExecutionOptions } from "../application/AnalysisProvider.js";
import type {
ModelArtifact,
ModelArtifactInput,
} from "../domain/model/modelArtifact.js";
import { modelArtifactSchema } from "../domain/model/modelArtifact.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisArtifactChangedError,
AnalysisAccessDeniedError,
AnalysisCancelledError,
AnalysisResourceConstraintError,
AnalysisUnsupportedTargetError,
} from "../domain/analysisErrorCore.js";
import { BinaryTargetError } from "../domain/configurationErrors.js";
import { ProviderAdapterError } from "../domain/providerAdapterError.js";
import { err, ok, type Result } from "../domain/result.js";
import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import {
withArtifactRegularFile,
bindArtifactFileCleanup,
artifactFilePrimaryFailure,
artifactFileCancellationCause,
ArtifactFileCancelled,
ArtifactFileCleanupFailure,
} from "../artifacts/ArtifactFileOperation.js";
import { analysisErrorWithCleanupFailure } from "../domain/analysisErrorCleanup.js";
import { ModelHeaderReader } from "./ModelHeaderReader.js";
import { GgufHeader } from "./GgufHeader.js";
import { readSafetensorsHeader } from "./SafetensorsHeader.js";
import {
ModelFormatFailure,
rejectModel,
MODEL_REPORT_BYTES,
MODEL_HEADER_BYTES,
} from "./ModelFormat.js";
import { safetensorsBits } from "./ModelTensorTypes.js";
import { jsonValueByteLength } from "../domain/jsonValueByteLength.js";
import { ProviderCleanupError } from "../domain/providerCleanupError.js";
import { sameRegularFileState } from "../filesystem/RegularFile.js";
export const MODEL_ARTIFACT_PROVIDER_IDENTITY = {
id: "model-artifact",
name: "REA model header reader",
version: "1",
} as const;
const OPERATION = "inspect_model_artifact";
/** One admitted descriptor and bounded report at a time; retained cleanup blocks new work. */
export class ModelArtifactProvider implements ModelArtifactPort {
readonly identity = MODEL_ARTIFACT_PROVIDER_IDENTITY;
readonly #resources = new ArtifactResourceScope();
#busy = false;
async close(): Promise<void> {
try {
await this.#resources.close();
} catch (cause) {
const error = new ProviderCleanupError(
this.identity.id,
this.#resources.cleanupResources,
{},
{ cause, operation: OPERATION },
);
bindArtifactFileCleanup(cause, error);
throw error;
}
}
async inspect(
input: ModelArtifactInput,
options?: ExecutionOptions,
): Promise<Result<ModelArtifact, AnalysisError>> {
if (this.#busy)
return err(
new AnalysisResourceConstraintError(
OPERATION,
"capacity",
"One model inspection is already active",
{ concurrent_inspections: 1 },
{ retryable: true },
),
);
this.#busy = true;
try {
return ok(
await this.#resources.run(() =>
withArtifactRegularFile(
input.path,
this.#resources,
options?.signal,
(file) => this.#read(file, input, options?.signal),
),
),
);
} catch (cause) {
const primary = artifactFilePrimaryFailure(cause);
let error: AnalysisError;
if (primary instanceof AnalysisError) error = primary;
else if (primary instanceof ModelFormatFailure) {
error =
primary.kind === "capacity"
? new AnalysisResourceConstraintError(
OPERATION,
"memory",
primary.message,
{
maximum_report_bytes: MODEL_REPORT_BYTES,
maximum_header_bytes: MODEL_HEADER_BYTES,
maximum_exact_offset: Number.MAX_SAFE_INTEGER,
},
{ cause, retryable: false },
)
: primary.kind === "unsupported"
? new AnalysisUnsupportedTargetError(
OPERATION,
input.path,
primary.message,
{ cause },
)
: new BinaryTargetError(input.path, primary.message, {
cause,
constraint: "file_format_rejected",
});
} else if (
primary instanceof ArtifactReaderFailure &&
primary.reason === "cancelled"
)
error = new AnalysisCancelledError(OPERATION, {
cause: artifactFileCancellationCause(primary),
});
else if (primary instanceof ArtifactFileCancelled)
error = new AnalysisCancelledError(OPERATION, {
cause: primary.fileCancellation.reason,
});
else if (
primary instanceof ArtifactReaderFailure &&
primary.reason === "integrity"
)
error = new AnalysisArtifactChangedError(
OPERATION,
input.path,
primary.message,
{ cause },
);
else if (
primary instanceof Error &&
"code" in primary &&
(primary.code === "EACCES" || primary.code === "EPERM")
)
error = new AnalysisAccessDeniedError(
OPERATION,
input.path,
primary.code,
{ cause: primary },
);
else if (
primary instanceof ArtifactReaderFailure &&
primary.reason === "limit"
)
error = new AnalysisResourceConstraintError(
OPERATION,
"memory",
primary.message,
{},
{ cause: primary },
);
else if (primary instanceof Error && "code" in primary)
error = new BinaryTargetError(input.path, primary.message, { cause });
else
error = new ProviderAdapterError(this.identity.id, OPERATION, {
cause,
diagnostics: {
path: input.path,
reason:
primary instanceof Error ? primary.message : String(primary),
},
});
if (
cause instanceof ArtifactReaderFailure &&
cause.cleanup !== undefined
) {
const cleanup = new ProviderCleanupError(
this.identity.id,
cause.cleanup.resources,
{ reason: cause.cleanup.reason },
{ cause, operation: OPERATION },
);
error = analysisErrorWithCleanupFailure(error, cleanup, OPERATION);
}
const completed =
cause instanceof ArtifactFileCleanupFailure &&
cause.fileCleanupFailure.outcome.kind === "completed"
? cause.fileCleanupFailure.outcome.value
: cause instanceof ArtifactFileCancelled
? cause.fileCancellation.outcome.value
: undefined;
if (completed !== undefined) {
// The descriptor owner retains observations even when its final close fails.
const report = modelArtifactSchema.safeParse(completed);
if (report.success)
error.retainPartialObservation(
createModelArtifactEvidence(report.data, this.identity, input),
);
}
bindArtifactFileCleanup(cause, error);
return err(error);
} finally {
this.#busy = false;
}
}
async #read(
file: FileHandle,
input: ModelArtifactInput,
signal?: AbortSignal,
): Promise<ModelArtifact> {
const initial = await file.stat({ bigint: true });
if (initial.size > BigInt(Number.MAX_SAFE_INTEGER))
throw new ModelFormatFailure(
"capacity",
"Model file exceeds exact host offset precision",
);
const reader = new ModelHeaderReader(file, Number(initial.size), signal);
const first = await reader.take(4);
if (
(first[0] === 0x80 && (first[1] ?? 0) >= 2 && (first[1] ?? 0) <= 5) ||
first.equals(Buffer.from([0x50, 0x4b, 3, 4]))
)
throw new ModelFormatFailure(
"unsupported",
"PyTorch pickle/ZIP model deserialization is unsupported; supply GGUF or safetensors instead",
);
const format = first.equals(Buffer.from("GGUF")) ? "gguf" : "safetensors";
const parsed =
format === "gguf"
? await new GgufHeader(reader).read()
: await readSafetensorsHeader(reader, first);
const intervals = parsed.tensors
.filter((row) => row.byte_length !== null)
.sort((a, b) => a.file_offset - b.file_offset);
let end = parsed.tensor_data_offset;
for (const row of intervals) {
if (row.file_offset < end && row.byte_length !== 0)
rejectModel(`Overlapping tensor byte ranges at ${row.name}`);
end = Math.max(end, row.file_offset + (row.byte_length ?? 0));
}
const header_length = reader.position;
const hashes = await reader.finish(input.hash === "full");
const after = await file.stat({ bigint: true });
const named = await lstat(input.path, { bigint: true }).catch(
(cause: unknown) => {
if (
cause instanceof Error &&
"code" in cause &&
["ENOENT", "ENOTDIR", "ELOOP"].includes(String(cause.code))
)
throw new ArtifactReaderFailure(
"integrity",
"Selected model path changed during inspection",
{ cause },
);
throw cause;
},
);
if ([after, named].some((stat) => !sameRegularFileState(initial, stat)))
throw new ArtifactReaderFailure(
"integrity",
"Model file changed during inspection",
);
const groups = new Map<
string,
{
type: string;
tensors: number;
parameter_count: bigint;
bytes: number | null;
}
>();
let parameters = 0n;
let bytes: number | null = 0;
for (const row of parsed.tensors) {
const count = BigInt(row.parameter_count);
parameters += count;
bytes =
bytes === null || row.byte_length === null
? null
: bytes + row.byte_length;
const group = groups.get(row.type) ?? {
type: row.type,
tensors: 0,
parameter_count: 0n,
bytes: 0,
};
group.tensors++;
group.parameter_count += count;
group.bytes =
group.bytes === null || row.byte_length === null
? null
: group.bytes + row.byte_length;
groups.set(row.type, group);
}
const unknownTypes = [
...new Set(
parsed.tensors
.filter(
(row) =>
row.byte_length === null ||
(format === "safetensors" &&
safetensorsBits(row.type) === undefined),
)
.map((row) => row.type),
),
];
const report = {
artifact: {
path: input.path,
file_size: Number(initial.size),
header_length,
...hashes,
read_scope:
input.hash === "full" ? ("full-file" as const) : ("header" as const),
},
format,
...parsed,
totals: {
confidence: "derived" as const,
parameter_count: parameters.toString(),
tensor_bytes: bytes,
by_type: [...groups.values()].map((group) => ({
...group,
parameter_count: group.parameter_count.toString(),
})),
},
coverage: {
header: "complete" as const,
tensor_data: "not-interpreted" as const,
array_values: parsed.metadata.every((row) => row.preview_complete)
? ("complete" as const)
: ("preview" as const),
storage_sizes: parsed.tensors.every(
(row) => row.storage_validation === "consistent",
)
? ("complete" as const)
: ("partial" as const),
tensor_ranges: parsed.tensors.every((row) => row.byte_length !== null)
? ("complete" as const)
: ("partial" as const),
},
limitations: [
"Facts are file declarations; model behavior, weight values and compatibility with an inference runtime were not verified.",
"Header SHA-256 commits only to the recorded prefix; file size is a separate observation. Different weights may share these declarations.",
...(input.hash === "header"
? ["Full-file SHA-256 is unknown because tensor data was not read."]
: [
"Full-file SHA-256 required streaming the entire file, including tensor data, without interpreting it.",
]),
...(parsed.metadata.some((row) => !row.preview_complete)
? [
"Metadata arrays retain at most eight elements per array; remaining values are omitted, with exact declared counts and source byte ranges.",
]
: []),
...(unknownTypes.length
? [
`Unknown tensor types prevent storage-size validation: ${unknownTypes.join(", ")}`,
]
: []),
],
};
if (jsonValueByteLength(report, MODEL_REPORT_BYTES) > MODEL_REPORT_BYTES)
throw new ModelFormatFailure("capacity", "Model report exceeds 32 MiB");
return modelArtifactSchema.parse(report);
}
}
+33
View File
@@ -0,0 +1,33 @@
/** Format failures stay separate from filesystem, capacity and cancellation failures. */
export class ModelFormatFailure extends Error {
constructor(
readonly kind: "format" | "unsupported" | "capacity",
message: string,
) {
super(message);
this.name = "ModelFormatFailure";
}
}
export function rejectModel(message: string): never {
throw new ModelFormatFailure("format", message);
}
// Safetensors' format ceiling is 100,000,000 bytes. The reader additionally
// bounds retained rows/text independently of that input ceiling.
export const MODEL_HEADER_BYTES = 100_000_000;
export const MODEL_REPORT_BYTES = 32 * 1024 * 1024;
export const MODEL_ARRAY_PREVIEW = 8;
/** Charge representation growth before retaining rows or decoding long strings. */
export class ModelReportBudget {
#remaining = MODEL_REPORT_BYTES;
charge(bytes: number): void {
if (!Number.isSafeInteger(bytes) || bytes < 0 || bytes > this.#remaining)
throw new ModelFormatFailure(
"capacity",
"Model facts exceed the 32 MiB retained representation budget",
);
this.#remaining -= bytes;
}
}
+138
View File
@@ -0,0 +1,138 @@
import { createHash } from "node:crypto";
import type { FileHandle } from "node:fs/promises";
import { assertArtifactReadActive } from "../artifacts/ArtifactFileOperation.js";
import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
import {
ModelFormatFailure,
MODEL_HEADER_BYTES,
rejectModel,
} from "./ModelFormat.js";
/** Sequential prefix reader. Read-ahead is permitted only inside a parser-proven header extent. */
export class ModelHeaderReader {
position = 0;
#end = 0;
#guaranteedEnd = 0;
#buffer = Buffer.alloc(0);
#start = 0;
#headerPrefixBytes = 0;
readonly #hash = createHash("sha256");
constructor(
readonly file: FileHandle,
readonly size: number,
readonly signal?: AbortSignal,
) {}
/** Safetensors declares JSON bytes separately from its fixed length prefix. */
excludeSafetensorsLengthPrefix(): void {
if (this.position !== 8)
throw new TypeError(
"Safetensors header budget must follow its eight-byte length prefix",
);
this.#headerPrefixBytes = 8;
}
/** Minimum bytes implied by the remaining declared header records, never tensor payload. */
guarantee(bytes: number): void {
const end = this.position + bytes;
this.#validateEnd(end);
this.#guaranteedEnd = Math.max(this.#guaranteedEnd, end);
}
#validateEnd(end: number): void {
if (!Number.isSafeInteger(end) || end < 0 || end > this.size)
rejectModel("Declared header extent is outside the file");
if (end - this.#headerPrefixBytes > MODEL_HEADER_BYTES)
throw new ModelFormatFailure(
"capacity",
"Model header exceeds 100,000,000 bytes",
);
}
async take(length: number): Promise<Buffer> {
assertArtifactReadActive(this.signal);
const end = this.position + length;
this.#validateEnd(end);
if (!Number.isSafeInteger(length) || length < 0)
rejectModel("Invalid header field length");
if (end > this.#end) {
const readEnd = Math.max(
end,
Math.min(this.position + 65536, this.#guaranteedEnd),
);
const retained = this.#buffer.subarray(this.position - this.#start);
const next = Buffer.allocUnsafe(readEnd - this.position);
retained.copy(next);
let offset = retained.length;
while (offset < next.length) {
assertArtifactReadActive(this.signal);
const result = await this.file.read(
next,
offset,
next.length - offset,
this.position + offset,
);
if (result.bytesRead === 0)
throw new ArtifactReaderFailure(
"integrity",
"Model header ended before its admitted file extent",
);
this.#hash.update(next.subarray(offset, offset + result.bytesRead));
offset += result.bytesRead;
}
this.#start = this.position;
this.#end = readEnd;
this.#buffer = next;
}
const result = this.#buffer.subarray(
this.position - this.#start,
end - this.#start,
);
this.position = end;
return result;
}
async consume(length: number): Promise<void> {
while (length > 0) {
const size = Math.min(length, 65536);
await this.take(size);
length -= size;
}
}
/** Complete the exact prefix commitment, optionally streaming weights without retaining them. */
async finish(full: boolean): Promise<{
header_sha256: string;
sha256: string | null;
bytes_read: number;
}> {
if (this.position !== this.#end)
rejectModel("Parser left unconsumed header bytes");
const header_sha256 = this.#hash.copy().digest("hex");
if (!full)
return { header_sha256, sha256: null, bytes_read: this.position };
const buffer = Buffer.allocUnsafe(1024 * 1024);
let position = this.position;
while (position < this.size) {
assertArtifactReadActive(this.signal);
const { bytesRead } = await this.file.read(
buffer,
0,
Math.min(buffer.length, this.size - position),
position,
);
if (bytesRead === 0)
throw new ArtifactReaderFailure(
"integrity",
"Model ended before its admitted extent during full-file hashing",
);
this.#hash.update(buffer.subarray(0, bytesRead));
position += bytesRead;
}
return {
header_sha256,
sha256: this.#hash.digest("hex"),
bytes_read: position,
};
}
}
+74
View File
@@ -0,0 +1,74 @@
/** ggml da8e2a54: enum ggml_type and block sizeof assertions in ggml-common.h.
* Unknown future IDs retain their numeric identity and an unknown byte length.
*/
const GGML_TYPES: Readonly<Record<number, readonly [string, number, number]>> =
{
0: ["F32", 1, 4],
1: ["F16", 1, 2],
2: ["Q4_0", 32, 18],
3: ["Q4_1", 32, 20],
6: ["Q5_0", 32, 22],
7: ["Q5_1", 32, 24],
8: ["Q8_0", 32, 34],
9: ["Q8_1", 32, 36],
10: ["Q2_K", 256, 84],
11: ["Q3_K", 256, 110],
12: ["Q4_K", 256, 144],
13: ["Q5_K", 256, 176],
14: ["Q6_K", 256, 210],
15: ["Q8_K", 256, 292],
16: ["IQ2_XXS", 256, 66],
17: ["IQ2_XS", 256, 74],
18: ["IQ3_XXS", 256, 98],
19: ["IQ1_S", 256, 50],
20: ["IQ4_NL", 32, 18],
21: ["IQ3_S", 256, 110],
22: ["IQ2_S", 256, 82],
23: ["IQ4_XS", 256, 136],
24: ["I8", 1, 1],
25: ["I16", 1, 2],
26: ["I32", 1, 4],
27: ["I64", 1, 8],
28: ["F64", 1, 8],
29: ["IQ1_M", 256, 56],
30: ["BF16", 1, 2],
34: ["TQ1_0", 256, 54],
35: ["TQ2_0", 256, 66],
39: ["MXFP4", 32, 17],
40: ["NVFP4", 64, 36],
41: ["Q1_0", 128, 18],
42: ["Q2_0", 64, 18],
};
export const ggmlType = (
id: number,
): readonly [string, number, number] | undefined => GGML_TYPES[id];
/** safetensors e246a256 Dtype::bitsize, including packed sub-byte types. */
const SAFETENSORS_BITS: Readonly<Record<string, number>> = {
BOOL: 8,
F4: 4,
F6_E2M3: 6,
F6_E3M2: 6,
I8: 8,
U8: 8,
F8_E5M2: 8,
F8_E4M3: 8,
F8_E8M0: 8,
F8_E4M3FNUZ: 8,
F8_E5M2FNUZ: 8,
I16: 16,
U16: 16,
F16: 16,
BF16: 16,
I32: 32,
U32: 32,
F32: 32,
I64: 64,
U64: 64,
F64: 64,
C64: 64,
};
export const safetensorsBits = (type: string): number | undefined =>
Object.hasOwn(SAFETENSORS_BITS, type) ? SAFETENSORS_BITS[type] : undefined;
+298
View File
@@ -0,0 +1,298 @@
import { setImmediate } from "node:timers/promises";
import { assertArtifactReadActive } from "../artifacts/ArtifactFileOperation.js";
import { TextDecoder } from "node:util";
import type {
ModelMetadata,
ModelTensor,
} from "../domain/model/modelArtifact.js";
import { ModelHeaderReader } from "./ModelHeaderReader.js";
import {
ModelFormatFailure,
ModelReportBudget,
rejectModel,
} from "./ModelFormat.js";
import { safetensorsBits } from "./ModelTensorTypes.js";
type HeaderValue =
| string
| number
| HeaderValue[]
| { [key: string]: HeaderValue };
/** The format's restricted JSON header, with duplicate keys and exact integer checks at its owner. */
class HeaderJson {
#position = 0;
#nodes = 0;
constructor(
readonly text: string,
readonly budget: ModelReportBudget,
) {}
#space(): void {
while (" \t\r\n".includes(this.text[this.#position] ?? "x"))
this.#position++;
}
#string(): string {
const start = this.#position++;
while (this.#position < this.text.length) {
const c = this.text[this.#position++];
if (c === "\\") this.#position++;
else if (c === '"') {
const raw = this.text.slice(start, this.#position);
this.budget.charge(6 * raw.length + 2);
try {
const value: unknown = JSON.parse(raw);
if (typeof value !== "string")
return rejectModel("Invalid JSON string");
for (const unit of value) {
const code = unit.codePointAt(0) ?? 0;
if (code >= 0xd800 && code <= 0xdfff)
rejectModel("Safetensors JSON contains an unpaired surrogate");
}
return value;
} catch (cause) {
if (cause instanceof SyntaxError)
rejectModel("Invalid safetensors JSON string");
throw cause;
}
}
}
return rejectModel("Unterminated safetensors JSON string");
}
*#value(depth: number): Generator<void, HeaderValue> {
if (++this.#nodes % 4096 === 0) yield;
this.#space();
this.budget.charge(64);
if (depth > 4)
rejectModel("Safetensors header has an invalid nested structure");
const c = this.text[this.#position];
if (c === '"') return this.#string();
if (c === "{" || c === "[") {
this.#position++;
const object: { [key: string]: HeaderValue } = Object.create(null) as {
[key: string]: HeaderValue;
};
const array: HeaderValue[] = [];
const close = c === "{" ? "}" : "]";
this.#space();
if (this.text[this.#position] === close) {
this.#position++;
return c === "{" ? object : array;
}
while (true) {
this.#space();
if (c === "{") {
if (this.text[this.#position] !== '"')
rejectModel("Expected safetensors JSON object key");
const key = this.#string();
if (Object.hasOwn(object, key))
rejectModel(`Duplicate safetensors JSON key ${key}`);
this.#space();
if (this.text[this.#position++] !== ":")
rejectModel("Expected safetensors JSON colon");
object[key] = yield* this.#value(depth + 1);
} else array.push(yield* this.#value(depth + 1));
this.#space();
const next = this.text[this.#position++];
if (next === close) return c === "{" ? object : array;
if (next !== ",") rejectModel("Invalid safetensors JSON container");
}
}
const start = this.#position;
while (/^[0-9]$/u.test(this.text[this.#position] ?? "")) this.#position++;
const raw = this.text.slice(start, this.#position);
if (!/^(?:0|[1-9][0-9]*)$/u.test(raw))
return rejectModel(
"Safetensors header requires unsigned integer declarations",
);
const number = Number(raw);
if (!Number.isSafeInteger(number))
throw new ModelFormatFailure(
"capacity",
"Safetensors integer exceeds exact host offset precision",
);
return number;
}
*read(): Generator<void, HeaderValue> {
if (this.text[0] !== "{")
rejectModel("Safetensors header must begin with a JSON object");
const value = yield* this.#value(0);
this.#space();
if (this.#position !== this.text.length)
rejectModel("Trailing non-whitespace safetensors header bytes");
return value;
}
}
const objectOf = (
value: HeaderValue | undefined,
): { [key: string]: HeaderValue } => {
if (value === undefined || typeof value !== "object" || Array.isArray(value))
return rejectModel("Expected safetensors header object");
return value;
};
const integersOf = (value: HeaderValue | undefined): number[] => {
if (
!Array.isArray(value) ||
!value.every((item): item is number => typeof item === "number")
)
return rejectModel("Expected safetensors integer array");
return value;
};
const pointer = (value: string): string =>
value.replaceAll("~", "~0").replaceAll("/", "~1");
export const readSafetensorsHeader = async (
reader: ModelHeaderReader,
first: Buffer,
): Promise<{
version: null;
byte_order: "little";
alignment: null;
tensor_data_offset: number;
metadata: ModelMetadata[];
tensors: ModelTensor[];
}> => {
const budget = new ModelReportBudget();
const second = await reader.take(4);
reader.excludeSafetensorsLengthPrefix();
const length =
BigInt(first.readUInt32LE()) + (BigInt(second.readUInt32LE()) << 32n);
if (length === 0n || (await reader.take(1))[0] !== 0x7b)
rejectModel("File does not contain a GGUF or safetensors header");
if (length > BigInt(Number.MAX_SAFE_INTEGER))
throw new ModelFormatFailure(
"capacity",
"Safetensors header length exceeds exact host offset precision",
);
const size = Number(length);
reader.guarantee(size - 1);
// Native UTF-8 decode and the bounded JSON parser both retain header text.
budget.charge(2 * size);
let text: string;
try {
text =
"{" +
new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
await reader.take(size - 1),
);
} catch (cause) {
if (cause instanceof TypeError)
rejectModel("Safetensors header is not valid UTF-8");
throw cause;
}
const steps = new HeaderJson(text, budget).read();
let step = steps.next();
while (!step.done) {
await setImmediate();
assertArtifactReadActive(reader.signal);
step = steps.next();
}
const root = objectOf(step.value);
const source = { source_offset: 8, source_length: size };
const metadata: ModelMetadata[] = [];
if (Object.hasOwn(root, "__metadata__")) {
for (const [key, value] of Object.entries(objectOf(root.__metadata__))) {
if (typeof value !== "string")
rejectModel("Safetensors __metadata__ values must be strings");
metadata.push({
index: metadata.length,
key,
type: "STRING",
value,
element_type: null,
element_count: null,
preview_complete: true,
...source,
json_pointer: `/__metadata__/${pointer(key)}`,
});
}
}
const tensors: ModelTensor[] = [];
const tensor_data_offset = 8 + size;
const names = Object.keys(root)
.filter((name) => name !== "__metadata__")
.sort();
budget.charge(names.length * 512);
for (const name of names) {
const entry = objectOf(root[name]);
if (
Object.keys(entry).length !== 3 ||
!Object.hasOwn(entry, "dtype") ||
!Object.hasOwn(entry, "shape") ||
!Object.hasOwn(entry, "data_offsets")
)
rejectModel(
`Safetensors tensor ${name} must declare dtype, shape and data_offsets`,
);
const type = entry.dtype;
if (typeof type !== "string")
rejectModel(`Safetensors tensor ${name} dtype must be a string`);
const shape = integersOf(entry.shape);
const offsets = integersOf(entry.data_offsets);
if (offsets.length !== 2)
rejectModel(`Safetensors tensor ${name} requires two data offsets`);
const start = offsets[0] ?? 0;
const end = offsets[1] ?? 0;
if (end < start || end > reader.size - tensor_data_offset)
rejectModel(
`Safetensors tensor ${name} range [${String(start)},${String(end)}) is outside the data buffer`,
);
let parameters = shape.includes(0) ? 0n : 1n;
if (parameters !== 0n)
for (const dimension of shape) {
parameters *= BigInt(dimension);
if (parameters > 0xffffffffffffffffn)
rejectModel(
`Safetensors tensor ${name} parameter count overflows uint64`,
);
}
const bits = safetensorsBits(type);
if (bits !== undefined) {
const expected = parameters * BigInt(bits);
if (expected % 8n !== 0n || expected / 8n !== BigInt(end - start))
rejectModel(
`Safetensors tensor ${name} byte length does not match dtype and shape`,
);
}
tensors.push({
index: tensors.length,
name,
type,
type_id: null,
shape: shape.map(String),
data_offset: start,
file_offset: tensor_data_offset + start,
byte_length: end - start,
parameter_count: parameters.toString(),
byte_length_state: "declared",
storage_validation: bits === undefined ? "unknown" : "consistent",
...source,
json_pointer: `/${pointer(name)}`,
});
}
const ordered = [...tensors].sort(
(a, b) =>
a.data_offset - b.data_offset ||
(a.byte_length ?? 0) - (b.byte_length ?? 0),
);
let end = 0;
for (const tensor of ordered) {
if (tensor.data_offset !== end)
rejectModel(
`Safetensors data ${tensor.data_offset < end ? "overlap" : "gap"} before ${tensor.name}: expected ${String(end)}, observed ${String(tensor.data_offset)}`,
);
end = tensor.data_offset + (tensor.byte_length ?? 0);
}
if (end !== reader.size - tensor_data_offset)
rejectModel(
`Safetensors unindexed trailing data: ${String(reader.size - tensor_data_offset - end)} bytes`,
);
return {
version: null,
byte_order: "little",
alignment: null,
tensor_data_offset,
metadata,
tensors,
};
};