Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(model): retain completed GGUF facts on interrupted reads

morlutoeb41f358cf83
diff --git a/src/application/model/ModelArtifactEvidence.ts b/src/application/model/ModelArtifactEvidence.ts
index 4eed8e5e0..8c6021496 100644
--- a/src/application/model/ModelArtifactEvidence.ts
+++ b/src/application/model/ModelArtifactEvidence.ts
@@ -1,6 +1,7 @@
import type { ProviderIdentity } from "../AnalysisProvider.js";
import type {
ModelArtifact,
+ ModelArtifactPartial,
ModelArtifactInput,
} from "../../domain/model/modelArtifact.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
@@ -32,3 +33,21 @@ export const createModelArtifactEvidence = (
},
);
};
+
+/** Evidence for completed GGUF facts retained before final identity verification. */
+export const createModelArtifactPartialEvidence = (
+ partial: ModelArtifactPartial,
+ provider: ProviderIdentity,
+ parameters: ModelArtifactInput,
+): Evidence =>
+ createEvidence(undefined, provider, {
+ operation: "inspect_model_artifact",
+ parameters: { path: parameters.path, hash: parameters.hash },
+ result: partial,
+ confidence: "observed",
+ subjectUnavailableReason:
+ "The interrupted read did not complete final file identity verification; digest and identity remain unknown.",
+ // Each retained row already owns its exact source offset and length.
+ locations: [{ kind: "artifact-path", path: partial.artifact.path }],
+ limitations: partial.limitations,
+ });
diff --git a/src/domain/model/modelArtifact.ts b/src/domain/model/modelArtifact.ts
index 0975096fb..104876a51 100644
--- a/src/domain/model/modelArtifact.ts
+++ b/src/domain/model/modelArtifact.ts
@@ -81,6 +81,48 @@ export const modelArtifactObjectSchema = z.strictObject({
limitations: z.array(z.string()),
});
+/** Facts proven before an interrupted GGUF read reached final file identity checks. */
+export const modelArtifactPartialTensorSchema = z.strictObject({
+ index: count,
+ name: z.string(),
+ type: z.string(),
+ type_id: count.nullable(),
+ shape: z.array(decimal),
+ data_offset: count,
+ file_offset: count.nullable(),
+ byte_length: count.nullable(),
+ parameter_count: decimal,
+ byte_length_state: z.enum(["derived", "declared", "unknown"]),
+ storage_validation: z.enum(["consistent", "unknown", "not-established"]),
+ ...location,
+});
+
+export const modelArtifactPartialSchema = z.strictObject({
+ kind: z.literal("model-artifact-partial"),
+ artifact: z.strictObject({
+ path: localPathStringSchema,
+ observed_file_size: count,
+ header_sha256: z.null(),
+ sha256: z.null(),
+ file_identity: z.literal("unverified"),
+ }),
+ format: z.literal("gguf"),
+ version: count.nullable(),
+ byte_order: z.enum(["little", "big"]).nullable(),
+ alignment: count.nullable(),
+ declared_metadata_count: count.nullable(),
+ declared_tensor_count: count.nullable(),
+ metadata: z.array(modelMetadataSchema),
+ tensor_declarations: z.array(modelArtifactPartialTensorSchema),
+ tensors: z.array(modelTensorSchema),
+ coverage: z.strictObject({
+ header: z.enum(["partial", "complete"]),
+ metadata: z.enum(["not-started", "partial", "complete"]),
+ tensors: z.enum(["not-started", "partial", "complete"]),
+ }),
+ limitations: z.array(z.string()),
+});
+
/** Lookup indexes are safe only after positional identities and uniqueness are proven. */
export const modelArtifactSchema = modelArtifactObjectSchema.superRefine(
(report, context) => {
@@ -125,6 +167,10 @@ export const modelArtifactSchema = modelArtifactObjectSchema.superRefine(
export type ModelArtifact = z.infer<typeof modelArtifactSchema>;
export type ModelTensor = z.infer<typeof modelTensorSchema>;
export type ModelMetadata = z.infer<typeof modelMetadataSchema>;
+export type ModelArtifactPartial = z.infer<typeof modelArtifactPartialSchema>;
+export type ModelArtifactPartialTensor = z.infer<
+ typeof modelArtifactPartialTensorSchema
+>;
export interface ModelArtifactInput {
readonly path: string;
readonly hash: "header" | "full";
diff --git a/src/model/GgufHeader.ts b/src/model/GgufHeader.ts
index 6998af4c6..7f598502d 100644
--- a/src/model/GgufHeader.ts
+++ b/src/model/GgufHeader.ts
@@ -4,6 +4,7 @@ import type { JsonValue } from "../domain/jsonValue.js";
import type {
ModelMetadata,
ModelTensor,
+ ModelArtifactPartialTensor,
} from "../domain/model/modelArtifact.js";
import { ModelHeaderReader } from "./ModelHeaderReader.js";
import {
@@ -31,6 +32,19 @@ const NAMES = [
] as const;
const WIDTHS = [1, 1, 2, 2, 4, 4, 4, 1, 8, 12, 8, 8, 8];
+export interface GgufProgress {
+ onHeader(info: {
+ version: number;
+ byte_order: "little" | "big";
+ declared_metadata_count: number;
+ declared_tensor_count: number;
+ }): void;
+ onMetadata(row: ModelMetadata): void;
+ onMetadataComplete(): void;
+ onTensorsStarted(): void;
+ onTensorDeclaration(row: ModelArtifactPartialTensor): void;
+}
+
/** Explicit-endian GGUF v2/v3 metadata and tensor-directory parser. */
export class GgufHeader {
#little = true;
@@ -216,7 +230,7 @@ export class GgufHeader {
};
}
- async read(): Promise<{
+ async read(progress?: GgufProgress): Promise<{
version: number;
byte_order: "little" | "big";
alignment: number;
@@ -239,6 +253,12 @@ export class GgufHeader {
rejectModel("Big-endian GGUF requires version 3");
const tensorCount = await this.#unsigned(8);
const metadataCount = await this.#unsigned(8);
+ progress?.onHeader({
+ version,
+ byte_order: this.#little ? "little" : "big",
+ declared_metadata_count: metadataCount,
+ declared_tensor_count: tensorCount,
+ });
this.#budget.charge((tensorCount + metadataCount) * 512);
this.reader.guarantee(tensorCount * 20 + metadataCount * 13);
const metadata: ModelMetadata[] = [];
@@ -259,7 +279,7 @@ export class GgufHeader {
keys.add(key);
const type = await this.#unsigned(4);
const parsed = await this.#value(type, true);
- metadata.push({
+ const row = {
index,
key,
type: NAMES[type] ?? String(type),
@@ -270,7 +290,7 @@ export class GgufHeader {
source_offset: start,
source_length: this.reader.position - start,
json_pointer: null,
- });
+ } satisfies ModelMetadata;
if (key === "general.alignment") {
if (
type !== 4 ||
@@ -283,8 +303,12 @@ export class GgufHeader {
);
alignment = parsed.value;
}
+ metadata.push(row);
+ progress?.onMetadata(row);
}
- const tensors: ModelTensor[] = [];
+ progress?.onMetadataComplete();
+ progress?.onTensorsStarted();
+ const tensors: ModelArtifactPartialTensor[] = [];
const names = new Set<string>();
for (let index = 0; index < tensorCount; index++) {
this.reader.guarantee((tensorCount - index) * 20);
@@ -321,22 +345,24 @@ export class GgufHeader {
);
length = Number(bytes);
}
- tensors.push({
+ const tensor = {
index,
name,
type: type?.[0] ?? `UNKNOWN_${String(id)}`,
type_id: id,
shape,
data_offset: offset,
- file_offset: 0,
+ file_offset: null,
byte_length: length,
parameter_count: parameters.toString(),
byte_length_state: length === null ? "unknown" : "derived",
- storage_validation: length === null ? "unknown" : "consistent",
+ storage_validation: "not-established",
source_offset: start,
source_length: this.reader.position - start,
json_pointer: null,
- });
+ } satisfies ModelArtifactPartialTensor;
+ tensors.push(tensor);
+ progress?.onTensorDeclaration(tensor);
}
const tensor_data_offset =
tensorCount === 0
@@ -351,13 +377,19 @@ export class GgufHeader {
rejectModel(`GGUF tensor ${tensor.name} range is outside the file`);
tensor.file_offset = Number(offset);
}
+ const completeTensors: ModelTensor[] = tensors.map((tensor) => ({
+ ...tensor,
+ file_offset: tensor.file_offset!,
+ storage_validation:
+ tensor.byte_length === null ? "unknown" : "consistent",
+ }));
return {
version,
byte_order: this.#little ? "little" : "big",
alignment,
tensor_data_offset,
metadata,
- tensors,
+ tensors: completeTensors,
};
}
}
diff --git a/src/model/ModelArtifactProvider.ts b/src/model/ModelArtifactProvider.ts
index 9e721998e..9265a140b 100644
--- a/src/model/ModelArtifactProvider.ts
+++ b/src/model/ModelArtifactProvider.ts
@@ -1,12 +1,19 @@
import { lstat, type FileHandle } from "node:fs/promises";
import type { ModelArtifactPort } from "../application/model/ModelArtifactPort.js";
-import { createModelArtifactEvidence } from "../application/model/ModelArtifactEvidence.js";
+import {
+ createModelArtifactEvidence,
+ createModelArtifactPartialEvidence,
+} from "../application/model/ModelArtifactEvidence.js";
import type { ExecutionOptions } from "../application/AnalysisProvider.js";
import type {
ModelArtifact,
+ ModelArtifactPartial,
ModelArtifactInput,
} from "../domain/model/modelArtifact.js";
-import { modelArtifactSchema } from "../domain/model/modelArtifact.js";
+import {
+ modelArtifactPartialSchema,
+ modelArtifactSchema,
+} from "../domain/model/modelArtifact.js";
import { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisArtifactChangedError,
@@ -86,6 +93,7 @@ export class ModelArtifactProvider implements ModelArtifactPort {
),
);
this.#busy = true;
+ let partialProgress: ModelArtifactPartial | undefined;
try {
return ok(
await this.#resources.run(() =>
@@ -93,7 +101,10 @@ export class ModelArtifactProvider implements ModelArtifactPort {
input.path,
this.#resources,
options?.signal,
- (file) => this.#read(file, input, options?.signal),
+ (file) =>
+ this.#read(file, input, options?.signal, (progress) => {
+ partialProgress = progress;
+ }),
),
),
);
@@ -207,6 +218,23 @@ export class ModelArtifactProvider implements ModelArtifactPort {
createModelArtifactEvidence(report.data, this.identity, input),
);
}
+ if (
+ error.partialObservation === undefined &&
+ partialProgress !== undefined &&
+ (partialProgress.metadata.length > 0 ||
+ partialProgress.tensor_declarations.length > 0 ||
+ partialProgress.tensors.length > 0)
+ ) {
+ const parsed = modelArtifactPartialSchema.safeParse(partialProgress);
+ if (parsed.success)
+ error.retainPartialObservation(
+ createModelArtifactPartialEvidence(
+ parsed.data,
+ this.identity,
+ input,
+ ),
+ );
+ }
bindArtifactFileCleanup(cause, error);
return err(error);
} finally {
@@ -218,6 +246,7 @@ export class ModelArtifactProvider implements ModelArtifactPort {
file: FileHandle,
input: ModelArtifactInput,
signal?: AbortSignal,
+ retainProgress?: (progress: ModelArtifactPartial) => void,
): Promise<ModelArtifact> {
const initial = await file.stat({ bigint: true });
if (initial.size > BigInt(Number.MAX_SAFE_INTEGER))
@@ -236,9 +265,60 @@ export class ModelArtifactProvider implements ModelArtifactPort {
"PyTorch pickle/ZIP model deserialization is unsupported; supply GGUF or safetensors instead",
);
const format = first.equals(Buffer.from("GGUF")) ? "gguf" : "safetensors";
+ let partial: ModelArtifactPartial | undefined;
+ if (format === "gguf") {
+ partial = {
+ kind: "model-artifact-partial",
+ artifact: {
+ path: input.path,
+ observed_file_size: Number(initial.size),
+ header_sha256: null,
+ sha256: null,
+ file_identity: "unverified",
+ },
+ format,
+ version: null,
+ byte_order: null,
+ alignment: null,
+ declared_metadata_count: null,
+ declared_tensor_count: null,
+ metadata: [],
+ tensor_declarations: [],
+ tensors: [],
+ coverage: {
+ header: "partial",
+ metadata: "not-started",
+ tensors: "not-started",
+ },
+ limitations: [
+ "This partial observation contains only rows fully parsed before the interrupted read.",
+ "Header and full-file digests and final file identity are unknown because finalization did not complete.",
+ "No model behavior or tensor payload values were interpreted.",
+ ],
+ };
+ retainProgress?.(partial);
+ }
const parsed =
format === "gguf"
- ? await new GgufHeader(reader).read()
+ ? await new GgufHeader(reader).read({
+ onHeader: (info) => {
+ if (partial === undefined) return;
+ partial.version = info.version;
+ partial.byte_order = info.byte_order;
+ partial.declared_metadata_count = info.declared_metadata_count;
+ partial.declared_tensor_count = info.declared_tensor_count;
+ partial.coverage.metadata = "partial";
+ },
+ onMetadata: (row) => partial?.metadata.push(row),
+ onMetadataComplete: () => {
+ if (partial !== undefined) partial.coverage.metadata = "complete";
+ },
+ onTensorsStarted: () => {
+ if (partial !== undefined) partial.coverage.tensors = "partial";
+ },
+ onTensorDeclaration: (row) =>
+ partial?.tensor_declarations.push(row),
+ })
: await readSafetensorsHeader(reader, first);
const intervals = parsed.tensors
.filter((row) => row.byte_length !== null)
@@ -249,6 +329,12 @@ export class ModelArtifactProvider implements ModelArtifactPort {
rejectModel(`Overlapping tensor byte ranges at ${row.name}`);
end = Math.max(end, row.file_offset + (row.byte_length ?? 0));
}
+ if (partial !== undefined && format === "gguf") {
+ partial.tensor_declarations = [];
+ partial.tensors = parsed.tensors;
+ partial.coverage.tensors = "complete";
+ partial.coverage.header = "complete";
+ }
const header_length = reader.position;
const hashes = await reader.finish(input.hash === "full");
const after = await file.stat({ bigint: true });
diff --git a/tests/boundary/mcp/modelArtifactPartialCancellation.test.ts b/tests/boundary/mcp/modelArtifactPartialCancellation.test.ts
new file mode 100644
index 000000000..cce8a409c
--- /dev/null
+++ b/tests/boundary/mcp/modelArtifactPartialCancellation.test.ts
@@ -0,0 +1,149 @@
+import { open, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { expect, vi } from "vitest";
+import { parseEvidence } from "../../../src/domain/evidence.js";
+import { ModelArtifactService } from "../../../src/application/model/ModelArtifactService.js";
+import { ModelArtifactProvider } from "../../../src/model/ModelArtifactProvider.js";
+import { InvestigationRecords } from "../../../src/application/investigation/InvestigationRecords.js";
+import { EvidenceMcpServer } from "../../../src/server/EvidenceMcpServer.js";
+import { registerModelArtifactTools } from "../../../src/server/registerModelArtifactTools.js";
+import { createToolResultDelivery } from "../../../src/server/toolResult.js";
+import { silentLogger } from "../../../src/logger.js";
+import { parseMcpToolError } from "../../fixtures/mcpToolError.js";
+import { ggufFixture } from "../../fixtures/model/model.js";
+import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
+import { mcpTest } from "../../support/mcp/mcpFixture.js";
+
+mcpTest.for([false, true])(
+ "projects partial model Evidence through an MCP tool error (retained=%s)",
+ async (retained, { mcp }) => {
+ const root = await createTestTempDirectory("rea-model-mcp-partial-");
+ const path = join(root, "model.gguf");
+ const seed = ggufFixture();
+ const count = 200_000;
+ const fixture = ggufFixture({
+ tensors: [],
+ metadata: [
+ { key: "general.name", type: 8, value: seed.text("First row") },
+ {
+ key: "custom.bools",
+ type: 9,
+ value: Buffer.concat([
+ seed.u32(7),
+ seed.u64(BigInt(count)),
+ Buffer.alloc(count),
+ ]),
+ },
+ ],
+ });
+ await writeFile(path, fixture.bytes);
+ const arrayStart =
+ 24 +
+ 8 +
+ Buffer.byteLength("general.name") +
+ 4 +
+ 8 +
+ Buffer.byteLength("First row") +
+ 8 +
+ Buffer.byteLength("custom.bools") +
+ 4 +
+ 4 +
+ 8;
+ const sample = await open(path, "r");
+ const prototype = Object.getPrototypeOf(sample) as {
+ read: (
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number,
+ ) => Promise<{ bytesRead: number }>;
+ };
+ await sample.close();
+ const originalRead = prototype.read;
+ const denied = Object.assign(new Error("controlled MCP read failure"), {
+ code: "EACCES",
+ });
+ let observedArrayChunk = false;
+ const readSpy = vi
+ .spyOn(prototype, "read")
+ .mockImplementation(async function (
+ this: unknown,
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number,
+ ) {
+ if (observedArrayChunk && position > arrayStart) throw denied;
+ const result = await originalRead.call(
+ this,
+ buffer,
+ offset,
+ length,
+ position,
+ );
+ if (position === arrayStart && result.bytesRead > 0)
+ observedArrayChunk = true;
+ return result;
+ });
+ const provider = new ModelArtifactProvider();
+ const server = new EvidenceMcpServer(
+ { name: "model-partial-test", version: "1" },
+ {},
+ undefined,
+ createToolResultDelivery(undefined),
+ );
+ const records = new InvestigationRecords();
+ registerModelArtifactTools(
+ server,
+ new ModelArtifactService(provider),
+ silentLogger,
+ retained ? (evidence) => records.recordEvidence(evidence) : undefined,
+ );
+ const client = await mcp.connect(server);
+ try {
+ const response = await client.callTool({
+ name: "inspect_model_artifact",
+ arguments: { path, detail: "complete" },
+ });
+ if (!observedArrayChunk) throw new Error(JSON.stringify(response));
+ const projected = parseMcpToolError(response);
+ const details = projected.error.details;
+ if (details === undefined)
+ throw new Error("MCP error omitted its partial observation");
+ let partial;
+ if (retained) {
+ expect(details.partial_observation).toMatchObject({
+ kind: "retained-evidence",
+ evidence_id: expect.any(String),
+ });
+ const reference = details.partial_observation as {
+ evidence_id: string;
+ };
+ partial = parseEvidence(records.evidenceById(reference.evidence_id));
+ } else partial = parseEvidence(details.partial_observation);
+ expect(partial.normalized_result).toMatchObject({
+ kind: "model-artifact-partial",
+ metadata: [
+ {
+ index: 0,
+ key: "general.name",
+ value: "First row",
+ source_offset: 24,
+ source_length: 41,
+ },
+ ],
+ artifact: {
+ path,
+ header_sha256: null,
+ sha256: null,
+ file_identity: "unverified",
+ },
+ });
+ expect(partial.locations).toEqual([{ kind: "artifact-path", path }]);
+ } finally {
+ readSpy.mockRestore();
+ await provider.close();
+ await rm(root, { recursive: true, force: true });
+ }
+ },
+);
diff --git a/tests/boundary/model/modelArtifactPartialCancellation.test.ts b/tests/boundary/model/modelArtifactPartialCancellation.test.ts
new file mode 100644
index 000000000..283aef67c
--- /dev/null
+++ b/tests/boundary/model/modelArtifactPartialCancellation.test.ts
@@ -0,0 +1,224 @@
+import { mkdtemp, open, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { expect, it, vi } from "vitest";
+import { ModelArtifactProvider } from "../../../src/model/ModelArtifactProvider.js";
+import { parseEvidence } from "../../../src/domain/evidence.js";
+import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";
+import { ggufFixture } from "../../fixtures/model/model.js";
+
+const cancelledArrayFixture = () => {
+ const seed = ggufFixture();
+ const count = 200_000;
+ const fixture = ggufFixture({
+ tensors: [],
+ metadata: [
+ { key: "general.name", type: 8, value: seed.text("First row") },
+ {
+ key: "custom.bools",
+ type: 9,
+ value: Buffer.concat([
+ seed.u32(7),
+ seed.u64(BigInt(count)),
+ Buffer.alloc(count),
+ ]),
+ },
+ ],
+ });
+ return {
+ fixture,
+ count,
+ arrayStart:
+ 24 +
+ 8 +
+ Buffer.byteLength("general.name") +
+ 4 +
+ 8 +
+ Buffer.byteLength("First row") +
+ 8 +
+ Buffer.byteLength("custom.bools") +
+ 4 +
+ 4 +
+ 8,
+ };
+};
+
+it("retains completed GGUF rows when cancellation interrupts a later value", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-model-partial-cancel-"));
+ const path = join(root, "model.gguf");
+ const { fixture, count, arrayStart } = cancelledArrayFixture();
+ await writeFile(path, fixture.bytes);
+ const sample = await open(path, "r");
+ const handlePrototype = Object.getPrototypeOf(sample) as {
+ read: (
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number,
+ ) => Promise<{ bytesRead: number }>;
+ };
+ await sample.close();
+ const originalRead = handlePrototype.read;
+ const controller = new AbortController();
+ const reason = { marker: "caller-selected-parser-cancel" };
+ let arrayBytesObserved = 0;
+ const readSpy = vi
+ .spyOn(handlePrototype, "read")
+ .mockImplementation(async function (
+ this: unknown,
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number,
+ ) {
+ const result = await originalRead.call(
+ this,
+ buffer,
+ offset,
+ length,
+ position,
+ );
+ if (position === arrayStart && result.bytesRead > 0) {
+ arrayBytesObserved = result.bytesRead;
+ controller.abort(reason);
+ }
+ return result;
+ });
+ const provider = new ModelArtifactProvider();
+ try {
+ const result = await provider.inspect(
+ { path, hash: "header" },
+ { signal: controller.signal },
+ );
+ if (result.ok) throw new Error("Expected parser cancellation");
+ expect(arrayBytesObserved).toBeGreaterThan(0);
+ expect(arrayBytesObserved).toBeLessThan(count);
+ expect(result.error.cause).toBe(reason);
+ const evidence = parseEvidence(result.error.partialObservation);
+ expect(evidence.subject).toBeNull();
+ expect(evidence.operation).toBe("inspect_model_artifact");
+ expect(evidence.normalized_result).toMatchObject({
+ kind: "model-artifact-partial",
+ artifact: {
+ path,
+ header_sha256: null,
+ sha256: null,
+ file_identity: "unverified",
+ },
+ coverage: {
+ header: "partial",
+ metadata: "partial",
+ tensors: "not-started",
+ },
+ metadata: [{ index: 0, key: "general.name", value: "First row" }],
+ tensors: [],
+ });
+ const projected = projectAnalysisError(result.error);
+ if (projected.details === undefined)
+ throw new Error("Projected error omitted its partial observation");
+ expect(parseEvidence(projected.details.partial_observation)).toEqual(
+ evidence,
+ );
+ } finally {
+ readSpy.mockRestore();
+ await provider.close();
+ await rm(root, { recursive: true, force: true });
+ }
+});
+
+it("retains completed GGUF tensor declarations before later tensor bytes cancel", async () => {
+ const root = await mkdtemp(join(tmpdir(), "rea-model-tensor-partial-"));
+ const path = join(root, "model.gguf");
+ const tensorCount = 4000;
+ const fixture = ggufFixture({
+ metadata: [],
+ tensors: Array.from({ length: tensorCount }, (_, index) => ({
+ name: `tensor-${String(index).padStart(4, "0")}`,
+ type: 0,
+ shape: [1n],
+ offset: 0n,
+ bytes: 4,
+ })),
+ });
+ await writeFile(path, fixture.bytes);
+ const sample = await open(path, "r");
+ const handlePrototype = Object.getPrototypeOf(sample) as {
+ read: (
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number,
+ ) => Promise<{ bytesRead: number }>;
+ };
+ await sample.close();
+ const originalRead = handlePrototype.read;
+ const controller = new AbortController();
+ const reason = { marker: "cancel-after-completed-tensor-declarations" };
+ let laterHeaderChunkSeen = false;
+ const readSpy = vi
+ .spyOn(handlePrototype, "read")
+ .mockImplementation(async function (
+ this: unknown,
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number,
+ ) {
+ const result = await originalRead.call(
+ this,
+ buffer,
+ offset,
+ length,
+ position,
+ );
+ if (position >= 24 + 65536 && result.bytesRead > 0) {
+ laterHeaderChunkSeen = true;
+ controller.abort(reason);
+ }
+ return result;
+ });
+ const provider = new ModelArtifactProvider();
+ try {
+ const result = await provider.inspect(
+ { path, hash: "header" },
+ { signal: controller.signal },
+ );
+ if (result.ok) throw new Error("Expected parser cancellation");
+ expect(laterHeaderChunkSeen).toBe(true);
+ expect(result.error.cause).toBe(reason);
+ const evidence = parseEvidence(result.error.partialObservation);
+ const partial = evidence.normalized_result as {
+ tensor_declarations: Array<{
+ index: number;
+ file_offset: number | null;
+ storage_validation: string;
+ }>;
+ tensors: unknown[];
+ coverage: { tensors: string };
+ artifact: {
+ path: string;
+ header_sha256: null;
+ sha256: null;
+ file_identity: string;
+ };
+ };
+ expect(partial.tensor_declarations.length).toBeGreaterThan(0);
+ expect(partial.tensor_declarations[0]).toMatchObject({
+ index: 0,
+ file_offset: null,
+ storage_validation: "not-established",
+ });
+ expect(partial.tensors).toEqual([]);
+ expect(partial.coverage.tensors).toBe("partial");
+ expect(partial.artifact).toMatchObject({
+ path,
+ header_sha256: null,
+ sha256: null,
+ file_identity: "unverified",
+ });
+ } finally {
+ readSpy.mockRestore();
+ await provider.close();
+ await rm(root, { recursive: true, force: true });
+ }
+});
diff --git a/tests/process-global/stableArtifactConsumers.test.ts b/tests/process-global/stableArtifactConsumers.test.ts
index 466570100..6c067ab96 100644
--- a/tests/process-global/stableArtifactConsumers.test.ts
+++ b/tests/process-global/stableArtifactConsumers.test.ts
@@ -10,6 +10,9 @@ const fault = vi.hoisted(() => ({
handles: [] as FileHandle[],
onClose: undefined as (() => void) | undefined,
readFailure: undefined as { cause: unknown } | undefined,
+ laterReadFailure: undefined as
+ | { position: number; cause: unknown }
+ | undefined,
}));
vi.mock("node:fs/promises", async (importOriginal) => {
@@ -28,6 +31,24 @@ vi.mock("node:fs/promises", async (importOriginal) => {
throw failure.cause;
};
}
+ if (fault.laterReadFailure !== undefined) {
+ const failure = fault.laterReadFailure;
+ const read = handle.read.bind(handle) as (
+ buffer: Buffer,
+ offset: number,
+ length: number,
+ position: number,
+ ) => Promise<{ bytesRead: number }>;
+ const instrumented = handle as unknown as { read: typeof read };
+ let observedStart = false;
+ instrumented.read = async (buffer, offset, length, position) => {
+ if (observedStart && position > failure.position) throw failure.cause;
+ const result = await read(buffer, offset, length, position);
+ if (position === failure.position && result.bytesRead > 0)
+ observedStart = true;
+ return result;
+ };
+ }
handle.close = async () => {
fault.onClose?.();
if (fault.blocked.has(handle))
@@ -78,6 +99,7 @@ beforeEach(() => {
fault.handles = [];
fault.onClose = undefined;
fault.readFailure = undefined;
+ fault.laterReadFailure = undefined;
});
const staticProviders = [
@@ -362,6 +384,74 @@ it("preserves a model permission failure when cancellation arrives during close"
}
});
+it("retains earlier GGUF rows and physical failure while retrying failed descriptor cleanup", async () => {
+ const path = await selectedImage();
+ const seed = ggufFixture();
+ const count = 200_000;
+ const fixture = ggufFixture({
+ tensors: [],
+ metadata: [
+ { key: "general.name", type: 8, value: seed.text("First row") },
+ {
+ key: "custom.bools",
+ type: 9,
+ value: Buffer.concat([
+ seed.u32(7),
+ seed.u64(BigInt(count)),
+ Buffer.alloc(count),
+ ]),
+ },
+ ],
+ });
+ await writeFile(path, fixture.bytes);
+ const arrayStart =
+ 24 +
+ 8 +
+ Buffer.byteLength("general.name") +
+ 4 +
+ 8 +
+ Buffer.byteLength("First row") +
+ 8 +
+ Buffer.byteLength("custom.bools") +
+ 4 +
+ 4 +
+ 8;
+ const denied = Object.assign(new Error("controlled later GGUF read denial"), {
+ code: "EACCES",
+ });
+ fault.laterReadFailure = { position: arrayStart, cause: denied };
+ const provider = new ModelArtifactProvider();
+ try {
+ const result = await provider.inspect({ path, hash: "header" });
+ if (result.ok) throw new Error("Expected physical read failure");
+ expect(result.error.cleanupPrimary).toBeInstanceOf(
+ AnalysisAccessDeniedError,
+ );
+ expect(result.error.cleanupPrimary?.cause).toBe(denied);
+ expect(result.error.cleanupIncomplete).toBe(true);
+ const partial = parseEvidence(result.error.partialObservation);
+ expect(partial.normalized_result).toMatchObject({
+ kind: "model-artifact-partial",
+ metadata: [{ index: 0, key: "general.name", value: "First row" }],
+ artifact: {
+ path,
+ header_sha256: null,
+ sha256: null,
+ file_identity: "unverified",
+ },
+ });
+ expect(fault.handles).toHaveLength(1);
+ expect(fault.handles[0]?.fd).toBeGreaterThanOrEqual(0);
+ fault.blocked.clear();
+ await provider.close();
+ expect(result.error.cleanupIncomplete).toBe(false);
+ expect(parseEvidence(result.error.partialObservation)).toEqual(partial);
+ } finally {
+ fault.blocked.clear();
+ await provider.close();
+ }
+});
+
mcpTest(
"retains Rust descriptor cleanup and recovers in the same MCP connection",
async ({ mcp }) => {