---
typeId: req
recordId: benac-io-007
fields:
  title: Package Bundle ZIP file structure
  statement: |
    A Package Bundle ZIP file shall be a ZIP file containing only regular file entries and directory entries.

    Every ZIP entry path shall be a UTF-8 relative path using `/` as the separator.

    A ZIP entry path shall not be empty, absolute, duplicated after path normalization, contain `\`, contain a `.` path component, contain a `..` path component, or identify platform metadata.

    A Package Bundle ZIP file shall contain `bundle/package_bundle_manifest.json`.

    A Host Implementation shall read `bundle/package_bundle_manifest.json` as the Package Bundle ZIP distribution contract.

    A Host Implementation shall compute the Package Bundle Manifest CID from the DRISL-encoded Package Bundle Manifest logical object.

    The Package Bundle Manifest shall not declare a field containing the CID of the Package Bundle Manifest itself.

    Every non-directory ZIP entry other than `bundle/package_bundle_manifest.json` shall be declared by the Package Bundle Manifest.

    Every declared included entry shall exist in the ZIP file.

    A Host Implementation shall reject a Package Bundle ZIP file containing undeclared non-directory entries.

    A Host Implementation shall reject a Package Bundle ZIP file missing a declared included entry.

    A Host Implementation shall not derive package import semantics from ZIP entry filenames, directory names, ZIP metadata, file ordering, file timestamps, file extensions, comments, compression method, host filesystem metadata, file permission bits, or undeclared JSON object fields.

    A ZIP entry shall have package import meaning only through the entry role declared for that path in the Package Bundle Manifest.

    For a structured document entry, import shall parse the JSON projection, validate the logical object, encode the logical object as DRISL, compute the structured document CID, and compare it to the CID declared in the Package Bundle Manifest.

    For a raw blob entry, import shall compute the raw blob CID over the exact decompressed entry bytes and compare it to the CID declared in the Package Bundle Manifest.

    Any unsafe path, duplicate path, undeclared entry, missing declared entry, parse failure, schema failure, CID mismatch, unsupported entry role, unsupported object type, unsupported schema version, resource-limit failure, or ZIP processing failure shall fail closed with a stable diagnostic record and raw diagnostic evidence handling.
  rationale: >-
    A Package Bundle ZIP file gives independent implementations a single
    package import file while allowing package distributions to include many
    content-addressed logical objects and byte artifacts. ZIP transport details
    must not become identity, trust, or authority.
  verification: >-
    Conformance tests cover valid ZIP import, missing manifest, invalid ZIP
    file, unsafe path, duplicate path, undeclared entry, missing declared
    entry, unsupported entry role, unsupported structured object type,
    unsupported schema version, structured document CID mismatch, raw blob CID
    mismatch, resource-limit failure, and filename-with-no-import-semantics.
    Each failure produces the required stable diagnostic classification code
    and raw diagnostic evidence disposition.
  testable: true
  status: draft
  area: BENAC-IO
  sourceDocument: operator ticket 2c9740bd-6943-49e6-bf89-6462e8993fd2
  sourceVersion: 2026-05-05
  sourceSections:
    - 10.15 Import, export, package bundles, and decentralized distribution
  order: 169
---
