Skip to content

bundle-import.md

Latest commit

 

History

History
100 lines (70 loc) · 2.77 KB

bundle-import.md

File metadata and controls

100 lines (70 loc) · 2.77 KB
Raw

akmon bundle import

Documented for Akmon 2.0.0.

Who this is for

Teams validating and ingesting portable .akmon bundles into local journals.

What you will have at the end

  • A verified bundle (--verify-only) or imported session.
  • Clear handling for collisions and archive validation failures.

Prerequisites

  • Path to a .akmon bundle file.
  • Write access to target journal if ingesting.

Steps

akmon bundle import <bundle-path> [OPTIONS]
akmon bundle import <bundle-path> \
  [--journal <path>] \
  [--format <human|json>] \
  [--verify-only] \
  [--allow-extra-files] \
  [--rename-to <NEW_UUID>]
  1. Validate bundle only (no local writes):
akmon bundle import /path/to/audit.akmon --verify-only
  1. Import into journal:
akmon bundle import /path/to/audit.akmon
  1. Resolve session-id collisions with rename:
akmon bundle import /path/to/audit.akmon --rename-to <new-uuid>
  1. Use JSON output in CI:
akmon bundle import /path/to/audit.akmon --verify-only --format json

Exit codes

Code Meaning
0 Bundle imported successfully (or verified successfully with --verify-only)
1 Bundle validation failed (AGEF integrity/structure violation)
2 Usage/recoverable import error (for example, session collision without suitable --rename-to)
3 I/O or environment error (bundle not found, unwritable journal, local store corruption)

Verification

akmon bundle import /path/to/audit.akmon --verify-only --format json | jq '.passed'

Expected result: true for valid bundle, otherwise false with violations and exit 1.

Validation checks (AGEF alignment)

Import validation aligns with AGEF structural/integrity requirements, including:

  • Manifest parse/schema-required fields
  • events.bin frame decoding (length-prefixed canonical CBOR events)
  • Event hash-chain integrity
  • Object closure (all referenced hashes present)
  • Object byte re-hash (bytes match hash key)
  • Head consistency (manifest.session.head matches terminal event hash)
  • Session boundary invariants (SessionStart first, SessionEnd terminal)
  • Sequence continuity (0..n-1)
  • Strict unknown-content handling by default (unknown event tags/statuses/extra archive files rejected unless flags permit)

Troubleshooting

  • If import exits 2 for collision, rerun with --rename-to <NEW_UUID>.
  • If verify-only exits 1, inspect JSON violations categories.
  • If import exits 3, check bundle path, journal permissions, and disk availability.

See also