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

+1
View File
@@ -414,6 +414,7 @@ const workflowAvailabilityFor = ({
name === "inspect_desktop_application" ||
name === "inspect_go_binary" ||
name === "inspect_il2cpp_metadata" ||
name === "inspect_model_artifact" ||
name === "inspect_rust_binary" ||
name === "inspect_electron_fuses"
)
@@ -22,6 +22,7 @@ import {
inspectAnalysisViewInputSchema,
projectAnalysisView,
type AnalysisViewResult,
type AnalysisViewRequest,
type InspectAnalysisViewInput,
} from "../../domain/analysisView/analysisView.js";
import { jsonValueSchema } from "../../domain/jsonValue.js";
@@ -233,6 +234,14 @@ export const requireAnalysisViewRetention = (
export const summarizeRetainedAnalysis = (
evidence: Evidence,
retention: AnalysisViewRetention,
): Result<Evidence, AnalysisError> =>
projectRetainedAnalysis(evidence, retention, { kind: "summary" });
/** Retain the complete owner observation and deliver one explicitly selected view. */
export const projectRetainedAnalysis = (
evidence: Evidence,
retention: AnalysisViewRetention,
view: AnalysisViewRequest,
): Result<Evidence, AnalysisError> => {
const ready = requireAnalysisViewRetention(evidence.operation, retention);
if (!ready.ok) return ready;
@@ -241,7 +250,7 @@ export const summarizeRetainedAnalysis = (
return inspectAnalysisViewValidated(
{
source: { kind: "retained-evidence", evidence_id: evidence.evidence_id },
view: { kind: "summary" },
view,
},
ready.value.evidenceById,
);
@@ -0,0 +1,34 @@
import type { ProviderIdentity } from "../AnalysisProvider.js";
import type {
ModelArtifact,
ModelArtifactInput,
} from "../../domain/model/modelArtifact.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
/** One Evidence interpretation for success and observations retained by file finalization failures. */
export const createModelArtifactEvidence = (
report: ModelArtifact,
provider: ProviderIdentity,
parameters: ModelArtifactInput,
): Evidence => {
const source = report.artifact;
return createEvidence(
source.sha256 === null
? undefined
: { path: source.path, sha256: source.sha256, format: "file" },
provider,
{
operation: "inspect_model_artifact",
parameters: { path: parameters.path, hash: parameters.hash },
result: report,
confidence: "observed",
subjectUnavailableReason:
"Full-file identity is unknown in header-only mode; normalized_result.artifact records a scoped header SHA-256 and exact source path/extent.",
locations: [
{ kind: "artifact-path", path: source.path },
{ kind: "file-offset-range", start: 0, end: source.header_length },
],
limitations: report.limitations,
},
);
};
@@ -0,0 +1,20 @@
import type {
ExecutionOptions,
ProviderIdentity,
} from "../AnalysisProvider.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type {
ModelArtifact,
ModelArtifactInput,
} from "../../domain/model/modelArtifact.js";
import type { Result } from "../../domain/result.js";
/** Read-only, local model declarations; no model runtime, target execution or downloads. */
export interface ModelArtifactPort {
readonly identity: ProviderIdentity;
inspect(
input: ModelArtifactInput,
options?: ExecutionOptions,
): Promise<Result<ModelArtifact, AnalysisError>>;
close(): Promise<void>;
}
@@ -0,0 +1,99 @@
import { inspectModelArtifactInputSchema } from "../../domain/model/modelArtifactQuery.js";
import type { ModelArtifactPort } from "./ModelArtifactPort.js";
import type { ExecutionOptions } from "../AnalysisProvider.js";
import { modelArtifactSchema } from "../../domain/model/modelArtifact.js";
import { analysisInputErrorFromIssues } from "../../domain/inputIssueProjection.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import {
AnalysisCancelledError,
AnalysisOutputError,
} from "../../domain/analysisErrorCore.js";
import type { Evidence } from "../../domain/evidence.js";
import { createModelArtifactEvidence } from "./ModelArtifactEvidence.js";
import { err, ok, type Result } from "../../domain/result.js";
import {
requireAnalysisViewRetention,
projectRetainedAnalysis,
type AnalysisViewRetention,
} from "../analysisView/AnalysisViewService.js";
/** Shared input, Evidence and retained delivery boundary for CLI, MCP and SDK callers. */
export class ModelArtifactService {
constructor(readonly provider: ModelArtifactPort) {}
close(): Promise<void> {
return this.provider.close();
}
async inspect(
raw: unknown,
options?: ExecutionOptions,
retention: AnalysisViewRetention = {
evidenceById: undefined,
recordEvidence: undefined,
},
): Promise<Result<Evidence, AnalysisError>> {
const input = inspectModelArtifactInputSchema.safeParse(raw);
if (!input.success)
return err(
analysisInputErrorFromIssues(
"inspect_model_artifact",
input.error.issues,
raw,
{ cause: input.error },
),
);
if (options?.signal?.aborted)
return err(
new AnalysisCancelledError("inspect_model_artifact", {
cause: options.signal.reason,
}),
);
const { detail, view, ...parameters } = input.data;
if (detail === "summary") {
const ready = requireAnalysisViewRetention(
"inspect_model_artifact",
retention,
);
if (!ready.ok) return ready;
}
const inspected = await this.provider.inspect(parameters, options);
if (!inspected.ok) return inspected;
const checked = modelArtifactSchema.safeParse(inspected.value);
if (
!checked.success ||
checked.data.artifact.path !== parameters.path ||
checked.data.artifact.read_scope !==
(parameters.hash === "full" ? "full-file" : "header") ||
(parameters.hash === "header"
? checked.data.artifact.sha256 !== null
: checked.data.artifact.sha256 === null)
)
return err(
new AnalysisOutputError(
"inspect_model_artifact",
"Model reader changed the selected input or returned invalid facts",
),
);
const report = checked.data;
const evidence = createModelArtifactEvidence(
report,
this.provider.identity,
parameters,
);
if (options?.signal?.aborted)
return err(
new AnalysisCancelledError("inspect_model_artifact", {
cause: options.signal.reason,
partialObservation: evidence,
}),
);
return detail === "summary"
? projectRetainedAnalysis(
evidence,
retention,
view === undefined
? { kind: "summary" }
: { kind: "model-artifact", ...view },
)
: ok(evidence);
}
}
+2
View File
@@ -7,6 +7,7 @@ import { createDirectAnalysis } from "./composition/directAnalysis.js";
import { registerEvmCommands } from "./cli/evmCommands.js";
import { registerDesktopApplicationCommands } from "./cli/desktopApplicationCommands.js";
import { registerGoCommands } from "./cli/goCommands.js";
import { registerModelCommands } from "./cli/modelCommands.js";
import { registerIl2cppCommands } from "./cli/il2cppCommands.js";
import { registerRustCommands } from "./cli/rustCommands.js";
import { registerSqliteCommands } from "./cli/sqliteCommands.js";
@@ -122,6 +123,7 @@ export const createCli = (
registerDesktopApplicationCommands(cli, logger);
registerGoCommands(cli, logger);
registerIl2cppCommands(cli, logger);
registerModelCommands(cli, logger);
registerRustCommands(cli, logger);
registerSqliteCommands(cli, logger, environment);
registerArtifactCommands(cli, logger, analysis.runProviderAnalysis);
+4 -1
View File
@@ -1,3 +1,4 @@
import type { AnalysisViewRequest } from "../domain/analysisView/analysisView.js";
import { z } from "incur";
import { parseEvidence, type Evidence } from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
@@ -34,6 +35,7 @@ const isEvidence = (value: JsonValue): value is Evidence =>
"normalized_result" in value;
interface CliEvidenceDelivery {
readonly view?: AnalysisViewRequest;
readonly providerId: string;
readonly operation: string;
readonly signal: AbortSignal;
@@ -95,6 +97,7 @@ export const deliverCliAnalysisEvidence = async (
signal,
detail,
evidenceOutput,
...(input.view === undefined ? {} : { view: input.view }),
});
};
@@ -139,7 +142,7 @@ export const publishCliAnalysisEvidence = async (
return detail === "summary"
? inspectAnalysisView({
source: { kind: "inline", evidence: complete },
view: { kind: "summary" },
view: input.view ?? { kind: "summary" },
})
: { ok: true as const, value: complete };
},
+105
View File
@@ -0,0 +1,105 @@
import { inspectModelArtifactInputSchema } from "../domain/model/modelArtifactQuery.js";
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { z } from "incur";
import type { Logger } from "pino";
import type { CliInstance } from "./types.js";
import { absoluteCallerPath } from "../filesystem/callerPath.js";
import { createModelArtifactService } from "../composition/model.js";
import { CLI_COMMANDS } from "../cliCommandNames.js";
import { logCliCommand } from "../cliLogging.js";
import { withCommandCancellation } from "./commandCancellation.js";
import {
analysisEvidenceDeliveryOptions,
deliverCliAnalysisEvidence,
} from "./analysisEvidenceDelivery.js";
/** One-shot summaries export the same complete observations used by MCP retained pages. */
export const registerModelCommands = (
cli: CliInstance,
logger: Logger,
): void => {
cli.command(CLI_COMMANDS.inspectModelArtifact, {
description:
"Inspect GGUF or safetensors headers without loading model weights",
args: z.object({
path: z.string().describe("Local model file, detected by content"),
}),
options: z.object({
...analysisEvidenceDeliveryOptions,
view: z
.string()
.optional()
.describe(
"JSON model page selection; requires --detail summary and --evidence_output",
),
hash: z
.enum(["header", "full"])
.default("header")
.describe(
"header reads declarations only; full additionally streams all bytes for SHA-256",
),
}),
run: ({ args, options }) =>
withCommandCancellation((signal) =>
logCliCommand(logger, CLI_COMMANDS.inspectModelArtifact, async () => {
let view: unknown;
try {
view =
options.view === undefined ? undefined : JSON.parse(options.view);
} catch (cause) {
return projectAnalysisError(
new AnalysisInputError("inspect_model_artifact", { cause }, [
{
path: ["view"],
reason: "invalid_format",
message: "view must be a JSON model page selection",
},
]),
);
}
const selected = inspectModelArtifactInputSchema.safeParse({
path: absoluteCallerPath(args.path),
hash: options.hash,
detail: options.detail,
...(view === undefined ? {} : { view }),
});
if (!selected.success)
return projectAnalysisError(
analysisInputErrorFromIssues(
"inspect_model_artifact",
selected.error.issues,
{ view },
),
);
const service = createModelArtifactService();
return deliverCliAnalysisEvidence({
run: () =>
service.inspect(
{
path: absoluteCallerPath(args.path),
hash: options.hash,
detail: "complete",
},
{ signal },
),
service,
providerId: "model-artifact",
operation: "inspect_model_artifact",
signal,
detail: options.detail,
evidenceOutput: options.evidence_output,
...(selected.data.view === undefined
? {}
: {
view: {
kind: "model-artifact" as const,
...selected.data.view,
},
}),
});
}),
),
});
};
+1
View File
@@ -61,6 +61,7 @@ export const CLI_COMMANDS = Object.freeze({
inspectDesktopApplication: "inspect-desktop-application",
inspectGoBinary: "inspect-go-binary",
inspectIl2cppMetadata: "inspect-il2cpp-metadata",
inspectModelArtifact: "inspect-model-artifact",
inspectRustBinary: "inspect-rust-binary",
inspectPeResources: "inspect-pe-resources",
inspectAnalysisView: "inspect-analysis-view",
+6
View File
@@ -0,0 +1,6 @@
import { ModelArtifactService } from "../application/model/ModelArtifactService.js";
import { ModelArtifactProvider } from "../model/ModelArtifactProvider.js";
/** Construct the local reader without acquiring files, processes or network resources. */
export const createModelArtifactService = (): ModelArtifactService =>
new ModelArtifactService(new ModelArtifactProvider());
+1 -1
View File
@@ -17,7 +17,7 @@ export const ANALYSIS_VIEW_TOOL_CONTRACTS = [
...toolContractMetadata("inspect_analysis_view"),
kind: "application",
description:
'Inspect selected views of completed Go build metadata, binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_macho, decode_interface_builder, inspect_evm_interface, inspect_managed_artifact, inspect_managed_members, inspect_android_package, inspect_dart_aot, inspect_il2cpp_metadata or inspect_web_network_capture Evidence without repeating analysis. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. Go metadata uses kind go, collection dependencies/settings, exact paths/keys or indices, fields and pagination. Row index refers to the original collection; empty selections return no rows, and dependency coverage remains unknown. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. The environment-manifest view projects the same HAR requests on the primary origin (most JSON-like records) into a replayable tool surface: view {kind: "environment-manifest", template_rules: ["after-uid-literal", "opaque-token", "sibling-variance"], include_query_parameter_names: true}. Each tool has a deterministic name, a path template and parameters from the four format rules plus the selected opt-in rules, observed query parameter names, a value-free body shape for POST/PUT/PATCH, status and content-type sets and record ordinals; records are pointers into the parent, excluded groups carry a reason and three fixed unknowns are always stated. Templates, parameters and names are inferences; the view copies no header, cookie or body values and refuses parents inspected with sensitive values. A capture_browser_scenario parent that selected response bodies or header values projects the same way, one record per network transaction in request order; it relies on capture-time redaction of declared secrets instead of that refusal, and a transaction whose URL was redacted is left unrepresented. The environment-state view extracts, from the same parents, the initial state the recorded reads observed: view {kind: "environment-state", template_rules: [...]} with the rules of the manifest it accompanies. It reads response bodies recorded before the first related write and reports entity types with an identity field (proved by a path parameter or inferred from a field name), entities in collection order with per-view values where views differ, documents for non-parameterized non-entity paths written by POST/PUT/PATCH (item-shaped and delete-only paths stay recorded), and a render plan per read tool: item and list views reproduce their latest recordings from the state, and every other read tool is a recorded view with a reason. Types and identity are inferences; values are recorded data, so it refuses parents inspected with sensitive values, and a scenario parent must have selected response bodies; its values keep the capture redaction markers, and a write whose URL it redacted ends the state of every type. For a retained record use source: {kind: "retained-evidence", evidence_id: "<parent_evidence_id>"}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: <complete Evidence>}. A completed Evidence JSON file on this host uses {kind: "evidence-file", path: "<absolute path>"}: REA reads and authenticates it, then projects it like retained Evidence, so a large capture is bounded by the file reader rather than by inline-input accounting. For layout, JavaScript, inventory, WASM, Mach-O, Interface Builder, EVM, managed artifact, Android package and Dart AOT sources, request a summary with view: {kind: "summary"}; summary is a view kind and has no facet. The WASM summary gives validation, counts, WAT digest/length, tool profile and execution/nLine truncated
'Inspect selected views of completed Go build metadata, binary-layout, JavaScript application, native analyze_function, inspect_artifact, inventory_artifact, inspect_wasm_artifact, inspect_macho, decode_interface_builder, inspect_evm_interface, inspect_managed_artifact, inspect_managed_members, inspect_android_package, inspect_dart_aot, inspect_il2cpp_metadata, inspect_model_artifact or inspect_web_network_capture Evidence without repeating analysis. Historical capture summaries return identity and counts without bodies or archive inventories. Capture views page retained records: view {kind: "capture", detail: "preview" | "complete", offset: 0, limit: 20}; preview selects recorded headline fields and binary descriptors, complete returns exact records with all sidecars. Offsets follow the selected parent record order, preserving original producer ordinals. Paging never reopens the source or reruns the decoder. Go metadata uses kind go, collection dependencies/settings, exact paths/keys or indices, fields and pagination. Row index refers to the original collection; empty selections return no rows, and dependency coverage remains unknown. For inspect_pcap_capture parents, kind pcap pages endpoints, dns-queries, tls-sni, protocols, http-uris or unattributed-addresses. Select an exact query for dns-addresses, or a tshark/capinfos stream for UTF-16 diagnostics text. Page totals count retained facts; source coverage remains explicit. Qlog summaries keep profile/scope and counts; kind qlog pages traces, streams, loss-declarations, incomplete-records, contributions, ranges or final-sizes. Except traces, select trace_index; stream-specific facets also require exact stream_id and direction. Facts retain all-recorded-events-before-selection scope, and interval overlap or endpoint loss declarations do not prove retransmission or network loss. The api-surface view groups retained HAR requests by method, origin and format-rule path template; templated segments are inferences. It reads no headers or bodies and reports no query values. The environment-manifest view projects the same HAR requests on the primary origin (most JSON-like records) into a replayable tool surface: view {kind: "environment-manifest", template_rules: ["after-uid-literal", "opaque-token", "sibling-variance"], include_query_parameter_names: true}. Each tool has a deterministic name, a path template and parameters from the four format rules plus the selected opt-in rules, observed query parameter names, a value-free body shape for POST/PUT/PATCH, status and content-type sets and record ordinals; records are pointers into the parent, excluded groups carry a reason and three fixed unknowns are always stated. Templates, parameters and names are inferences; the view copies no header, cookie or body values and refuses parents inspected with sensitive values. A capture_browser_scenario parent that selected response bodies or header values projects the same way, one record per network transaction in request order; it relies on capture-time redaction of declared secrets instead of that refusal, and a transaction whose URL was redacted is left unrepresented. The environment-state view extracts, from the same parents, the initial state the recorded reads observed: view {kind: "environment-state", template_rules: [...]} with the rules of the manifest it accompanies. It reads response bodies recorded before the first related write and reports entity types with an identity field (proved by a path parameter or inferred from a field name), entities in collection order with per-view values where views differ, documents for non-parameterized non-entity paths written by POST/PUT/PATCH (item-shaped and delete-only paths stay recorded), and a render plan per read tool: item and list views reproduce their latest recordings from the state, and every other read tool is a recorded view with a reason. Types and identity are inferences; values are recorded data, so it refuses parents inspected with sensitive values, and a scenario parent must have selected response bodies; its values keep the capture redaction markers, and a write whose URL it redacted ends the state of every type. For a retained record use source: {kind: "retained-evidence", evidence_id: "<parent_evidence_id>"}. Use normalized_result.parent_evidence_id from a summary receipt. Source kind is required. Portable source uses {kind: "inline", evidence: <complete Evidence>}. A completed Evidence JSON file on this host uses {kind: "evidence-file", path: "<absolute path>"}: REA reads and authenticates it, then projects it like retained Evidence, so a large capture is bounded by the file reader rather than by inline-input accounting. For layout, JavaScript, inventory, WASM, Mach-O, Interface Builder, EVM, managed artifact, Android package and Dart AOT sources, request a summary with view: {kind: "summary"}; summary is a view kind and has no facet. The WASM summary gives validation, counts, WAT digest/length, toolLine truncated
inputSchema: inspectAnalysisViewInputSchema,
outputSchema: evidenceResultOf(analysisViewResultSchema),
examples: [
+38
View File
@@ -0,0 +1,38 @@
import { inspectModelArtifactInputSchema } from "../../domain/model/modelArtifactQuery.js";
import { z } from "zod";
import { modelArtifactSchema } from "../../domain/model/modelArtifact.js";
import {
modelArtifactPageViewResultSchema,
modelArtifactSummaryViewResultSchema,
} from "../../domain/analysisView/analysisView.js";
import type { ToolContract } from "../toolContractTypes.js";
import { toolContractMetadata } from "../toolEffects.js";
import { evidenceResultOf } from "../toolOutputSchemaPrimitives.js";
export const MODEL_TOOL_CONTRACTS = [
{
name: "inspect_model_artifact",
...toolContractMetadata("inspect_model_artifact"),
kind: "artifact-provider",
description:
"Inspect local GGUF v2/v3 or safetensors declarations by content, without loading models or executing code. Default hash header reads only the header: full-file SHA-256 and Evidence subject are unknown; artifact.header_sha256 is a scoped prefix commitment, not weight identity. hash full additionally streams all file bytes for SHA-256. Optional view returns a selected metadata/tensor/type page plus model context in this call. Summary retains complete Evidence for inspect_analysis_view kind model-artifact, collection metadata (keys/indices/fields) or tensors (names/types/indices/fields), with stable header-scoped indices and paging. Metadata arrays retain eight-element typed previews; scalar metadata is complete. Tensor counts, shapes, types and offsets are observed; parameter/storage totals are derived from declarations. Unknown GGUF types retain IDs with unknown byte lengths. Tensor payload, model behavior and inference quality are not inspected. One active inspection, 100 MB header ceiling and 32 MiB retained-facts budget; resource refusals are explicit. No network, external files, Python, model runtime, extraction or deserialization of pickle.",
inputSchema: inspectModelArtifactInputSchema,
outputSchema: evidenceResultOf(
z.union([
modelArtifactSchema,
modelArtifactSummaryViewResultSchema,
modelArtifactPageViewResultSchema,
]),
),
examples: [
{
title: "Read model declarations without reading weights",
input: {
path: "/artifacts/model.gguf",
hash: "header",
detail: "summary",
},
},
],
},
] as const satisfies readonly ToolContract[];
+2
View File
@@ -4,6 +4,7 @@ import { WASM_TOOL_CONTRACTS } from "./wasm/wasmToolContracts.js";
import { EVM_TOOL_CONTRACTS } from "./evm/evmToolContracts.js";
import { DESKTOP_APPLICATION_TOOL_CONTRACTS } from "./desktopApplicationToolContracts.js";
import { GO_TOOL_CONTRACTS } from "./go/goToolContracts.js";
import { MODEL_TOOL_CONTRACTS } from "./model/modelToolContracts.js";
import { IL2CPP_TOOL_CONTRACTS } from "./il2cpp/il2cppToolContracts.js";
import { RUST_TOOL_CONTRACTS } from "./rust/rustToolContracts.js";
import { SQLITE_TOOL_CONTRACTS } from "./sqlite/sqliteToolContracts.js";
@@ -49,6 +50,7 @@ export const TOOL_CONTRACTS = [
...EVM_TOOL_CONTRACTS,
...GO_TOOL_CONTRACTS,
...IL2CPP_TOOL_CONTRACTS,
...MODEL_TOOL_CONTRACTS,
...RUST_TOOL_CONTRACTS,
...WASM_TOOL_CONTRACTS,
...SQLITE_TOOL_CONTRACTS,
+2
View File
@@ -66,6 +66,8 @@ const EXECUTION_WORDING_EXCEPTIONS: Readonly<Record<string, string>> = {
"inspects the operator-selected adb client; never starts its server",
list_adb_devices: "may start the local adb server, which REA does not own",
inspect_firmware_regions: "states there is no target execution",
inspect_model_artifact:
"states that model code and inference are never executed",
extract_firmware: "states that extracted code is never executed",
analyze_javascript_application: "reconstructs the graph without executing",
reconcile_javascript_runtime: "never invents execution claims",
+1
View File
@@ -128,6 +128,7 @@ export const TOOL_EFFECTS: Readonly<Record<string, ToolEffects>> = {
inspect_desktop_application: evidence,
inspect_go_binary: evidence,
inspect_il2cpp_metadata: evidence,
inspect_model_artifact: evidence,
inspect_rust_binary: evidence,
inspect_sqlite_database: effects({
mutatesSession: true,
+27
View File
@@ -1,3 +1,10 @@
import {
projectModelArtifactView,
modelArtifactSummarySchema,
modelArtifactViewRequestSchema,
modelArtifactViewItemsSchema,
modelArtifactViewContextSchema,
} from "./modelArtifactView.js";
import {
goBinarySummarySchema,
goBinaryViewContextSchema,
@@ -283,6 +290,7 @@ export const analysisViewRequestSchema = z.discriminatedUnion("kind", [
pcapViewRequestSchema,
dartAotViewRequestSchema,
il2cppMetadataViewRequestSchema,
modelArtifactViewRequestSchema,
]);
// The application owns admission and authenticated Evidence parsing. SDK and
@@ -386,6 +394,7 @@ const viewResultBase = {
"inspect_pcap_capture",
"inspect_dart_aot",
"inspect_il2cpp_metadata",
"inspect_model_artifact",
...NATIVE_INVENTORY_OPERATIONS,
"match_native_functions",
]),
@@ -527,6 +536,21 @@ export const dartAotSummaryViewResultSchema = z.strictObject({
summary: dartAotSummarySchema,
});
export const modelArtifactSummaryViewResultSchema = z.strictObject({
...summaryViewResultBase,
parent_operation: z.literal("inspect_model_artifact"),
summary: modelArtifactSummarySchema,
});
export const modelArtifactPageViewResultSchema = z.strictObject({
kind: z.literal("model-artifact"),
view: modelArtifactViewRequestSchema,
items: modelArtifactViewItemsSchema,
...viewResultBase,
...modelArtifactViewContextSchema.shape,
parent_operation: z.literal("inspect_model_artifact"),
});
/** Metadata identity and row counts for selected IL2CPP delivery. */
export const il2cppMetadataSummaryViewResultSchema = z.strictObject({
...summaryViewResultBase,
@@ -610,6 +634,7 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
pcapCaptureSummaryViewResultSchema,
dartAotSummaryViewResultSchema,
il2cppMetadataSummaryViewResultSchema,
modelArtifactSummaryViewResultSchema,
nativeInventorySummaryViewResultSchema,
nativeFunctionMatchingSummaryViewResultSchema,
]),
@@ -756,6 +781,7 @@ export const analysisViewResultSchema = z.discriminatedUnion("kind", [
...dartAotViewContextSchema.shape,
parent_operation: z.literal("inspect_dart_aot"),
}),
modelArtifactPageViewResultSchema,
z.strictObject({
kind: z.literal("il2cpp-metadata"),
view: il2cppMetadataViewRequestSchema,
@@ -891,6 +917,7 @@ const retainedViewProjectors = new Map<string, typeof projectWasmArtifactView>([
["inspect_android_package", projectAndroidPackageView],
["inspect_dart_aot", projectDartAotView],
["inspect_il2cpp_metadata", projectIl2cppMetadataView],
["inspect_model_artifact", projectModelArtifactView],
["match_native_functions", projectNativeFunctionMatchingView],
["inspect_artifact", projectArtifactInventoryView],
["inventory_artifact", projectArtifactInventoryView],
@@ -0,0 +1,337 @@
import {
modelTypeRowSchema,
modelArtifactViewRequestSchema,
} from "../model/modelArtifactQuery.js";
export { modelArtifactViewRequestSchema } from "../model/modelArtifactQuery.js";
import { z } from "zod";
import {
modelArtifactSchema,
modelArtifactObjectSchema,
modelMetadataSchema,
modelTensorSchema,
modelSourceSchema,
type ModelArtifact,
} from "../model/modelArtifact.js";
import type { AnalysisError } from "../analysisErrorBase.js";
import { analysisViewInputError } from "./analysisViewErrors.js";
import { parseAnalysisViewResult } from "./analysisViewParent.js";
import { isImmutableJsonSnapshot } from "../immutableJson.js";
import type { JsonValue } from "../jsonValue.js";
import { err, ok, type Result } from "../result.js";
import type {
AnalysisViewParent,
AnalysisViewRequest,
UnsignedAnalysisView,
} from "./analysisView.js";
import {
completeWithinViewCoverage,
boundedViewMessages,
pageViewCoverage,
} from "./analysisViewCoverage.js";
const HEADLINE_TEXT_LIMIT = 512;
export const modelArtifactSummarySchema = modelArtifactObjectSchema
.omit({ metadata: true, tensors: true, totals: true })
.extend({
totals: modelArtifactObjectSchema.shape.totals.omit({ by_type: true }),
counts: z.strictObject({
metadata: z.number().int().nonnegative(),
tensors: z.number().int().nonnegative(),
types: z.number().int().nonnegative(),
}),
headlines: z.array(
modelMetadataSchema.omit({
source_offset: true,
source_length: true,
json_pointer: true,
}),
),
chat_template_present: z.boolean(),
});
const summarizeModel = (
report: ModelArtifact,
): z.infer<typeof modelArtifactSummarySchema> => {
const {
tensors,
metadata,
totals: { by_type, ...totals },
...identity
} = report;
const headlineKeys = new Set([
"general.architecture",
"general.name",
"general.file_type",
"tokenizer.ggml.model",
"format",
]);
const architecture = metadata.find(
(row) => row.key === "general.architecture",
)?.value;
if (
typeof architecture === "string" &&
architecture.length <= HEADLINE_TEXT_LIMIT - ".context_length".length
)
headlineKeys.add(`${architecture}.context_length`);
return {
...identity,
totals,
counts: {
tensors: tensors.length,
metadata: metadata.length,
types: by_type.length,
},
headlines: metadata
.filter(
(row) =>
headlineKeys.has(row.key) &&
row.element_count === null &&
row.element_type === null &&
row.type.length <= HEADLINE_TEXT_LIMIT &&
(row.value === null ||
typeof row.value === "boolean" ||
typeof row.value === "number" ||
(typeof row.value === "string" &&
row.value.length <= HEADLINE_TEXT_LIMIT)),
)
.map(
({
source_offset: _offset,
source_length: _length,
json_pointer: _pointer,
...row
}) => row,
),
chat_template_present: metadata.some(
(row) => row.key === "tokenizer.chat_template",
),
};
};
const modelContextSchema = modelArtifactSummarySchema.omit({
artifact: true,
coverage: true,
limitations: true,
});
export const modelArtifactViewItemsSchema = z.union([
z.array(modelTypeRowSchema.partial().required({ index: true })),
z.array(modelTensorSchema.partial().required({ index: true })),
z.array(modelMetadataSchema.partial().required({ index: true })),
]);
export const modelArtifactViewContextSchema = z.strictObject({
source: modelSourceSchema,
model: modelContextSchema,
source_coverage: modelArtifactObjectSchema.shape.coverage,
});
type Checked = {
report: ModelArtifact;
summary: z.infer<typeof modelArtifactSummarySchema>;
model: z.infer<typeof modelContextSchema>;
names: Map<string, number>;
keys: Map<string, number>;
typeRows: z.infer<typeof modelTypeRowSchema>[];
types: Map<string, number>;
};
const checked = new WeakMap<object, Checked>();
const read = (parent: AnalysisViewParent): Result<Checked, AnalysisError> => {
const key = parent.normalizedResult;
const reusable =
parent.sealedResult === true &&
key !== null &&
typeof key === "object" &&
isImmutableJsonSnapshot(key);
const cached = reusable ? checked.get(key) : undefined;
if (cached !== undefined) return ok(cached);
const parsed = parseAnalysisViewResult(modelArtifactSchema, parent);
if (!parsed.ok) return parsed;
const report = reusable ? (key as ModelArtifact) : parsed.value;
if (
parent.subject != null &&
(parent.subject.local_path !== report.artifact.path ||
parent.subject.digest.sha256 !== report.artifact.sha256)
)
return err(
analysisViewInputError([
{
path: ["source", "subject"],
reason: "invalid_value",
message:
"Model full-file subject does not match its recorded artifact",
},
]),
);
const summary = summarizeModel(report);
const {
artifact: _artifact,
coverage: _coverage,
limitations: _limitations,
...model
} = summary;
const value = {
report,
summary,
model,
typeRows: report.totals.by_type.map((row, index) => ({ index, ...row })),
types: new Map(
report.totals.by_type.map((row, index) => [row.type, index]),
),
names: new Map(report.tensors.map((row) => [row.name, row.index])),
keys: new Map(report.metadata.map((row) => [row.key, row.index])),
};
if (reusable) checked.set(key, value);
return ok(value);
};
/** Historical pages never reopen weights or report a scoped header digest as full-file identity. */
export const projectModelArtifactView = (
parent: AnalysisViewParent,
view: AnalysisViewRequest,
): Result<UnsignedAnalysisView, AnalysisError> => {
if (view.kind !== "summary" && view.kind !== "model-artifact")
return err(
analysisViewInputError([
{
path: ["view"],
reason: "invalid_value",
message:
"Model Evidence supports summary and model-artifact metadata/tensor pages",
},
]),
);
const parsed = read(parent);
if (!parsed.ok) return parsed;
const {
report,
summary,
model,
names,
keys,
types: typeIndices,
typeRows,
} = parsed.value;
const shared = {
parent_evidence_id: parent.evidenceId,
parent_operation: "inspect_model_artifact" as const,
parent_digest: parent.evidenceId.slice(3),
artifact: { path: report.artifact.path, sha256: report.artifact.sha256 },
limitations: boundedViewMessages(
parent.limitations,
parent.evidenceId,
"limitations",
),
unknowns: [
"Tensor values, runtime execution and inference quality were not inspected.",
...(report.artifact.sha256 === null
? [
"Full-file content identity is unknown; header_sha256 commits only to declarations.",
]
: []),
],
};
if (view.kind === "summary")
return ok({
kind: "summary",
view,
...shared,
summary: {
...summary,
limitations: boundedViewMessages(
summary.limitations,
parent.evidenceId,
"limitations",
),
},
coverage: completeWithinViewCoverage(1, 1),
});
const rows =
view.collection === "tensors"
? report.tensors
: view.collection === "metadata"
? report.metadata
: typeRows;
const selectedNames =
view.collection === "tensors"
? view.names
: view.collection === "metadata"
? view.keys
: view.types;
const lookup =
view.collection === "tensors"
? names
: view.collection === "metadata"
? keys
: typeIndices;
const indices =
view.indices === undefined ? undefined : new Set(view.indices);
const types =
view.collection === "tensors" && view.types !== undefined
? new Set(view.types)
: undefined;
const storageStates =
view.collection === "tensors" && view.storage_validation !== undefined
? new Set(view.storage_validation)
: undefined;
let selected: number[] | undefined;
if (selectedNames !== undefined)
selected = [
...new Set(
selectedNames.flatMap((name) => {
const index = lookup.get(name);
return index === undefined ? [] : [index];
}),
),
].sort((a, b) => a - b);
else if (indices !== undefined)
selected = [...indices]
.filter((index) => index < rows.length)
.sort((a, b) => a - b);
if (
indices !== undefined ||
types !== undefined ||
storageStates !== undefined
)
selected = (selected ?? rows.map((row) => row.index)).filter((index) => {
const row = rows[index]!;
return (
(indices === undefined || indices.has(index)) &&
(types === undefined || types.has(row.type)) &&
(storageStates === undefined ||
("storage_validation" in row &&
storageStates.has(row.storage_validation)))
);
});
const total = selected?.length ?? rows.length;
const pageIndices =
selected === undefined
? Array.from(
{
length: Math.max(
0,
Math.min(view.limit, rows.length - view.offset),
),
},
(_, index) => view.offset + index,
)
: selected.slice(view.offset, view.offset + view.limit);
const fields =
view.fields === undefined ? undefined : new Set<string>(view.fields);
const items = pageIndices.map((index) => {
const row = rows[index]!;
const result: Record<string, JsonValue> = { index };
for (const [name, value] of Object.entries(row))
if (fields === undefined || fields.has(name)) result[name] = value;
return result;
});
return ok({
kind: "model-artifact",
view,
...shared,
source: report.artifact,
model,
source_coverage: report.coverage,
items: modelArtifactViewItemsSchema.parse(items),
coverage: pageViewCoverage(view.offset, items.length, total),
});
};
+131
View File
@@ -0,0 +1,131 @@
import { z } from "zod";
import { localPathStringSchema } from "../localPath.js";
import { digestSchema } from "../digests.js";
import { jsonValueSchema } from "../jsonValue.js";
const count = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
const decimal = z.string().regex(/^(?:0|[1-9][0-9]*)$/u);
export const modelSourceSchema = z.strictObject({
path: localPathStringSchema,
file_size: count,
header_sha256: digestSchema,
header_length: count,
sha256: digestSchema.nullable(),
bytes_read: count,
read_scope: z.enum(["header", "full-file"]),
});
const location = {
source_offset: count,
source_length: count,
json_pointer: z.string().nullable(),
};
/** Arrays retain declared types/counts and bounded observations, never an implicit full vocabulary. */
export const modelMetadataSchema = z.strictObject({
index: count,
key: z.string(),
type: z.string(),
value: jsonValueSchema,
element_type: z.string().nullable(),
element_count: count.nullable(),
preview_complete: z.boolean(),
...location,
});
export const modelTensorSchema = z.strictObject({
index: count,
name: z.string(),
type: z.string(),
type_id: count.nullable(),
shape: z.array(decimal),
data_offset: count,
file_offset: count,
byte_length: count.nullable(),
parameter_count: decimal,
byte_length_state: z.enum(["derived", "declared", "unknown"]),
storage_validation: z.enum(["consistent", "unknown"]),
...location,
});
export const modelArtifactObjectSchema = z.strictObject({
artifact: modelSourceSchema,
format: z.enum(["gguf", "safetensors"]),
version: count.nullable(),
byte_order: z.enum(["little", "big"]),
alignment: count.nullable(),
tensor_data_offset: count,
metadata: z.array(modelMetadataSchema),
tensors: z.array(modelTensorSchema),
totals: z.strictObject({
confidence: z.literal("derived"),
parameter_count: decimal,
tensor_bytes: count.nullable(),
by_type: z.array(
z.strictObject({
type: z.string(),
tensors: count,
parameter_count: decimal,
bytes: count.nullable(),
}),
),
}),
coverage: z.strictObject({
header: z.literal("complete"),
tensor_data: z.literal("not-interpreted"),
array_values: z.enum(["complete", "preview"]),
tensor_ranges: z.enum(["complete", "partial"]),
storage_sizes: z.enum(["complete", "partial"]),
}),
limitations: z.array(z.string()),
});
/** Lookup indexes are safe only after positional identities and uniqueness are proven. */
export const modelArtifactSchema = modelArtifactObjectSchema.superRefine(
(report, context) => {
const collections = [
{ name: "metadata", rows: report.metadata, identity: "key" },
{ name: "tensors", rows: report.tensors, identity: "name" },
{ name: "totals.by_type", rows: report.totals.by_type, identity: "type" },
] as const;
for (const { name, rows, identity } of collections) {
const seen = new Set<string>();
const prefix = name.split(".");
for (let index = 0; index < rows.length; index++) {
const row = rows[index]!;
if ("index" in row && row.index !== index) {
context.addIssue({
code: "custom",
path: [...prefix, index, "index"],
message: "Model row index must equal its source position",
});
return;
}
const value =
identity === "key" && "key" in row
? row.key
: identity === "name" && "name" in row
? row.name
: row.type;
if (seen.has(value)) {
context.addIssue({
code: "custom",
path: [...prefix, index, identity],
message: "Model collection identities must be unique",
});
return;
}
seen.add(value);
}
}
},
);
export type ModelArtifact = z.infer<typeof modelArtifactSchema>;
export type ModelTensor = z.infer<typeof modelTensorSchema>;
export type ModelMetadata = z.infer<typeof modelMetadataSchema>;
export interface ModelArtifactInput {
readonly path: string;
readonly hash: "header" | "full";
}
+82
View File
@@ -0,0 +1,82 @@
import { z } from "zod";
import { absoluteLocalPathStringSchema } from "../localPath.js";
import {
modelArtifactObjectSchema,
modelMetadataSchema,
modelTensorSchema,
} from "./modelArtifact.js";
export const modelTypeRowSchema =
modelArtifactObjectSchema.shape.totals.shape.by_type.element.extend({
index: z.number().int().nonnegative(),
});
const page = {
indices: z.array(z.number().int().nonnegative()).optional(),
offset: z.number().int().nonnegative().default(0),
limit: z.number().int().positive().default(32),
};
const tensorSelectionSchema = z.strictObject({
...page,
collection: z.literal("tensors"),
names: z.array(z.string()).optional(),
storage_validation: z
.array(modelTensorSchema.shape.storage_validation)
.optional(),
types: z.array(z.string()).optional(),
fields: z.array(modelTensorSchema.keyof()).optional(),
});
const typeSelectionSchema = z.strictObject({
...page,
collection: z.literal("types"),
types: z.array(z.string()).optional(),
fields: z.array(modelTypeRowSchema.keyof()).optional(),
});
const metadataSelectionSchema = z.strictObject({
...page,
collection: z.literal("metadata"),
keys: z.array(z.string()).optional(),
fields: z.array(modelMetadataSchema.keyof()).optional(),
});
export const modelArtifactSelectionSchema = z.discriminatedUnion("collection", [
tensorSelectionSchema,
typeSelectionSchema,
metadataSelectionSchema,
]);
export const modelArtifactViewRequestSchema = z.discriminatedUnion(
"collection",
[
tensorSelectionSchema.extend({ kind: z.literal("model-artifact") }),
typeSelectionSchema.extend({ kind: z.literal("model-artifact") }),
metadataSelectionSchema.extend({ kind: z.literal("model-artifact") }),
],
);
/** Selection changes delivery; full observations remain retained. */
export const inspectModelArtifactInputSchema = z
.strictObject({
path: absoluteLocalPathStringSchema,
hash: z
.enum(["header", "full"])
.default("header")
.describe(
"header reads declarations only; full streams all bytes for SHA-256",
),
detail: z.enum(["summary", "complete"]).default("summary"),
view: modelArtifactSelectionSchema
.optional()
.describe(
"Return this selected page with compact model context, retaining complete Evidence; requires summary detail",
),
})
.superRefine((value, context) => {
if (value.view !== undefined && value.detail === "complete")
context.addIssue({
code: "custom",
path: ["view"],
message:
"view selects summary delivery; omit view to request complete Evidence",
});
});
+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,
};
};
+12
View File
@@ -27,6 +27,8 @@ import { createRecordedCrashService } from "../composition/binaryDiagnostics.js"
import { createDesktopApplicationService } from "../composition/desktop.js";
import { registerDesktopApplicationTool } from "./registerDesktopApplicationTool.js";
import { createGoBinaryService } from "../composition/go.js";
import { createModelArtifactService } from "../composition/model.js";
import { registerModelArtifactTools } from "./registerModelArtifactTools.js";
import { createIl2cppMetadataService } from "../composition/il2cpp.js";
import type { Il2cppMetadataService } from "../application/il2cpp/Il2cppMetadataService.js";
import type { GoBinaryService } from "../application/go/GoBinaryService.js";
@@ -329,6 +331,7 @@ export const createServer = (
const desktopApplication = createDesktopApplicationService();
const goBinary = options.goBinary ?? createGoBinaryService();
const rustBinary = options.rustBinary ?? createRustBinaryService();
const modelArtifact = createModelArtifactService();
const il2cppMetadata =
options.il2cppMetadata ?? createIl2cppMetadataService();
const peResources = createPeResourcesService();
@@ -416,6 +419,7 @@ export const createServer = (
goBinary.close(),
rustBinary.close(),
il2cppMetadata.close(),
modelArtifact.close(),
peResources.close(),
electronFuses.close(),
webNetworkCapture.close(),
@@ -491,6 +495,14 @@ export const createServer = (
analysisAdmission,
evidenceById,
);
registerModelArtifactTools(
server,
modelArtifact,
toolLogger,
recordEvidence,
analysisAdmission,
evidenceById,
);
registerBinaryAnalysisTools(toolContext);
registerReverseEngineeringTools(
server,
+34
View File
@@ -0,0 +1,34 @@
import type { EvidenceMcpServer } from "./EvidenceMcpServer.js";
import type { EvidenceLookup } from "../application/EvidenceInputResolver.js";
import type { ModelArtifactService } from "../application/model/ModelArtifactService.js";
import type { EvidenceWriter } from "../application/investigation/InvestigationRecordPort.js";
import type { Logger } from "pino";
import type { WithAdmittedAnalysis } from "./analysisAdmission.js";
import { toolContract } from "../contracts/toolContracts.js";
import { createEvidenceToolHandler } from "./contractToolHandler.js";
import { toolRegistrationOptions } from "./toolRegistrationOptions.js";
/** Bind the named model contract to the shared inspection and session Evidence owners. */
export const registerModelArtifactTools = (
server: EvidenceMcpServer,
service: ModelArtifactService,
logger: Logger,
recordEvidence?: EvidenceWriter["recordEvidence"],
withAdmittedAnalysis?: WithAdmittedAnalysis,
evidenceById?: EvidenceLookup,
): void => {
const contract = toolContract("inspect_model_artifact");
const handler = createEvidenceToolHandler(
server,
(input, options) =>
service.inspect(input, options, { recordEvidence, evidenceById }),
logger,
recordEvidence,
withAdmittedAnalysis,
);
server.registerTool(
contract.name,
toolRegistrationOptions(contract),
handler(contract),
);
};