Skip to main content

MPK Contract

This document defines the authoritative contract for model-archive ingestion and MPK-contract parsing.

Scope​

The contract applies to:

  • src/model/ModelPack.cpp
  • src/model/ModelArchiveLoader.cpp
  • src/model/internal/ModelArchiveLoader.h
  • src/pipeline/internal/sima/MpkContract.cpp
  • src/pipeline/internal/sima/static_contract/MpkDecoder.cpp

Accepted Archive Format​

Accepted package extension: exact lowercase .tar.gz only. .mpk, .tgz, .tar, and bare .gz are rejected before tar inspection.

Archive requirements:

  • Archive must be readable as a tar stream.
  • Archive size must be <= loader configured max_archive_bytes.
  • Number of entries must be <= loader configured max_entries.
  • Entry payload size must be <= loader configured max_entry_bytes.

Allowed Layout​

Only regular files are accepted for extraction. Directory entries are allowed but ignored.

Allowed extracted file classes:

  • JSON config files (*.json) -> extracted under etc/
  • Shared objects (*.so) -> extracted under lib/
  • ELF binaries (*.elf) -> extracted under share/

Required package content:

  • The MPK inference contract (mpk.json or *_mpk.json)
  • Loader-side stage/config JSON needed by the runtime
  • At least one model binary artifact (*.elf or *.so)

MPK Manifest Loading​

Model loading, prepared-runtime builds, and the PCIe host read mpk.json through MpkDecoder::load. It reads the manifest once, builds the semantic MpkContract from those bytes, and resolves each stage executable inside the package: MLA executables from share/, lib/, then the package root; A65 modules from lib/, the package root, then share/. Execution admission and the PCIe host decode the same bytes with the executables' ELF and GraphExecutor evidence, so the plan and the contract come from the same bytes.

Extraction Safety Rules​

Extraction must be fail-closed.

Rejected path forms:

  • Absolute paths (for example /etc/passwd)
  • Traversal segments (..)
  • Windows drive prefixes (C:)
  • Mixed separator traversal forms (..\\, ..//)
  • Invalid UTF-8 path bytes
  • Unicode slash/backslash confusables (for example U+FF0F, U+2215, U+FF3C)
  • Unicode dot confusables used in traversal-like paths (for example U+FF0E, U+2024, U+FE52)

Rejected entry types:

  • Symlink entries
  • Hardlink entries
  • Device entries
  • FIFO entries

Extraction behavior:

  • Never write archive paths directly to filesystem output paths.
  • Normalize and validate archive entry path first.
  • Extract approved entries by content stream into a controlled temp root.
  • Never allow writes outside extraction root.
  • Duplicate normalized tar paths are rejected as invalid_archive.
  • Tar header/checksum corruption is rejected as invalid_archive.

JSON and Sequence Validation​

pipeline_sequence.json must satisfy:

  • JSON object with non-empty pipelines array.
  • First pipeline object must contain non-empty sequence array.
  • Each stage entry must include:
    • sequence_id (integer)
    • name (non-empty string)
    • pluginId (non-empty string)
    • configPath (non-empty string)
    • processor (non-empty string)
    • kernel (non-empty string)
  • Duplicate stage names are rejected.
  • Duplicate JSON keys are rejected.
  • JSON nesting deeper than loader max_json_depth is rejected.
  • Unsupported kernel values are rejected.
  • Stage dependencies in input must only reference:
    • decoder, or
    • earlier stage names after stable ordering.

Error Taxonomy​

All model-archive or MPK-contract ingestion failures must map to one of the following classes:

  • invalid_archive
  • path_traversal
  • schema_error
  • unsupported_version
  • size_limit_exceeded

Public error messages must include the taxonomy key so tests can assert deterministic classification.

Determinism Requirements​

  • Sequence ordering must be deterministic across repeated runs.
  • Fixture archives under tests/assets/mpk must be reproducible bit-for-bit.
  • Generated fixture manifest checksums under test-assets/model-archive/fixtures_manifest.json are the source of truth for build-tree security fixtures.

Test Mapping Requirement​

Every negative model-archive/MPK-contract test must assert one of the taxonomy keys above.