Skip to main content

Module bundle

Module bundle 

Source
Expand description

.hmc — a transparent container-of-files bundle for shipping a set of sealed assets (.10d / .q42 / .p64) as one attestable unit. Available to both native and WASM builds (native adds the zero-copy BundleMmap). .hmc — the hyper-media-container: a transparent container-of-files bundle for shipping a set of sealed Qualia assets (.emf spectral media, .10d meshes, .q42 graph volumes, .p64 weights, …) as one attestable unit (a release artefact, a downloadable pack, a signed asset set).

§Why a bundle, and why transparent

The Qualia container family (.10d / .q42 / .p64) are all internally navigable — you can pull a segment (a mesh section, a subgraph, a weight shard) without reading the whole file, ideally mmap zero-copy. A bundle must not destroy that. So a .hmc bundle only concatenates intact files, page-aligned, with an index of absolute offsets — it never compresses, re-chunks, or reframes an entry. Consequences:

  • reader.get(key) returns a zero-copy slice that is a byte-identical standalone file — feed it straight to the existing .q42/.10d/.p64 reader; its interior offsets resolve unchanged.
  • reader.segment(key, off, len) reaches an interior segment of an entry directly — the bundle does not interfere with segment-level access.
  • HTTP range-fetching one interior segment works: entry.offset + seg.off.

It lives in qualia-core-db so it is one reader for both channels — native (BundleMmap, zero-copy) and WASM (parse fetched/ranged bytes).

See format for the on-disk layout.

Re-exports§

pub use entity_compiler as twin_compiler;
pub use entity_verifier as twin_verifier;
pub use streaming_hydration::DEFAULT_HYDRATION_QUEUE_CAPACITY;
pub use streaming_hydration::EcopunkPackStreamer;
pub use streaming_hydration::HmcPackStreamer;
pub use streaming_hydration::LocalHostQ42Ext;
pub use entity_compiler::compile_digital_twin;
pub use entity_compiler::compile_entity;
pub use entity_compiler::EntityCompileInput;
pub use entity_compiler::EntityCompileOutput;
pub use entity_compiler::TwinCompileInput;
pub use entity_compiler::TwinCompileOutput;
pub use entity_verifier::verify_digital_twin_10d;
pub use entity_verifier::verify_digital_twin_bundle;
pub use entity_verifier::verify_entity_10d;
pub use entity_verifier::verify_entity_bundle;
pub use entity_verifier::AffordanceVerificationSummary;
pub use entity_verifier::CommonsObligationSummary;
pub use entity_verifier::DigitalTwin10dVerification;
pub use entity_verifier::DigitalTwinBundleVerification;
pub use entity_verifier::Entity10dVerification;
pub use entity_verifier::EntityBundleVerification;
pub use entity_verifier::ImpostorVerificationSummary;
pub use entity_verifier::SurfelVerificationSummary;
pub use cbor_ld_manifest::AcousticAnchors;
pub use cbor_ld_manifest::CborLdManifest;
pub use cbor_ld_manifest::CommonsObligation;
pub use cbor_ld_manifest::CredentialProof;
pub use cbor_ld_manifest::CredentialSubject;
pub use cbor_ld_manifest::GeometryLayout;
pub use cbor_ld_manifest::SectionLayoutEntry;
pub use cbor_ld_manifest::SubjectAffordances;
pub use cbor_ld_manifest::CBOR_LD_CONTEXT_CREDENTIALS_V1;
pub use cbor_ld_manifest::CBOR_LD_CONTEXT_WEBCIVICS_V1;
pub use cbor_ld_manifest::CBOR_LD_MANIFEST_ENTRY_KEY;
pub use cbor_ld_manifest::CBOR_LD_MANIFEST_KIND;
pub use species_meta::FaunaSpeciesMeta;
pub use species_meta::FloraSpeciesMeta;
pub use species_meta::HolisticSpeciesMeta;
pub use species_meta::MechanicalAssemblyMeta;
pub use species_meta::SPECIES_META_ENTRY_KEY;
pub use species_meta::SPECIES_META_KIND;
pub use streaming_loader::classify_10d_section_tier;
pub use streaming_loader::classify_entry_tier;
pub use streaming_loader::verify_arrived_range;
pub use streaming_loader::HmcHeaderProbe;
pub use streaming_loader::HmcProgressiveRangePlanner;
pub use streaming_loader::HmcRangeRequest;
pub use streaming_loader::StreamPriorityTier;
pub use variant_matrix::BiologicalPhenotype;
pub use variant_matrix::EntityFamilyManifest;
pub use variant_matrix::LodTier;
pub use variant_matrix::ModelVariantDescriptor;
pub use variant_matrix::StructuralState;
pub use variant_matrix::TwinFamilyManifest;
pub use variant_matrix::FAMILY_MANIFEST_ENTRY_KEY;
pub use variant_matrix::FAMILY_MANIFEST_KIND;
pub use field_range_planner::*;

Modules§

cbor_ld_manifest
CBOR-LD Self-Contained Verifiable Credential Manifest for .hmc Bundles.
entity_compiler
Reverse-LOD Ontological Entity Compiler & Asset Packaging Engine.
entity_verifier
Automated Ontological Entity Verification Engine (.10d & .hmc).
field_range_planner
Selective chunk-aligned range planning and arrived-chunk verification for .emf (v4 Q42EMF64) and .qac (v1 qac\0\0\0\0\0) entries embedded inside .hmc bundles.
species_meta
Domain metadata schemas for .hmc holistic entity digital twins.
stream
Bounded QBDL streaming admission. Structural checks do not confer authority.
streaming_hydration
Byte-Backed WASM .q42 Host Seam, Progressive Range-Streamed .hmc Delivery, Webizen-Governed Worker Pool & Hardware Texture Transcoding Pipeline.
streaming_loader
Progressive HTTP Range / OPFS slice streaming loader for .hmc bundles.
variant_matrix
Multi-Model Variant Matrix & Digital Twin Family Manifest for .hmc Bundles.

Structs§

BundleEntry
One row of the bundle index (the CBOR footer). Describes one intact embedded file: its logical key, its format kind, where it lives (absolute, aligned), its length, a SHA-256 of the exact bytes, and opaque per-entry meta (a nested CBOR blob whose schema is agreed by the producer/consumer of a given bundle kind — e.g. an anatomy pack stores each organ’s body-system, position and default colour there). The bundle format itself stays domain- agnostic: it moves intact files; meta carries any domain semantics.
BundleMmap
Open a .hmc bundle from disk via mmap for zero-copy access (native).
BundleReadLimits
Caller-owned cold admission limits. decoded_index_bytes is a conservative logical reservation (four times retained storage plus scratch), not measured RSS or an allocator/stack guarantee. Payload bytes continue to borrow the input.
BundleReader
A parsed, integrity-checked view over a .hmc bundle’s bytes. Borrows the input; get/segment return slices into it (zero copy).
BundleWriter
Accumulates intact files and serialises them into a .hmc bundle.

Enums§

BundleError
An error building or reading a .hmc bundle.

Constants§

BUNDLE_ENTRY_ALIGN
Alignment (bytes) applied to every entry payload and the index footer. Page alignment (64) preserves the interior page-alignment of embedded .q42 / .p64 / .10d files, so their own segment offsets stay aligned and mmap / zero-copy segment access into an entry is unaffected. This matches the Page alignment tier of the container_10d writer and p64_weight.
BUNDLE_FLAG_PAGE_ALIGN_4096
Header flag indicating every entry and index footer is aligned to 4096 bytes.
BUNDLE_HEADER_SIZE
Fixed header size in bytes. Payloads begin at (or after) this offset.
BUNDLE_MAGIC
Magic bytes at the start of every .hmc (hyper-media-container) bundle: QBDL. The 4-byte on-disk format tag is retained across the .qualia→.hmc rename (extension ≠ magic, as with most formats), so bundles already built keep parsing; only the file extension and human-facing name changed.
BUNDLE_PAGE_ALIGN_4096
OS page alignment (4096 bytes) for zero-copy direct mmap paging of embedded assets.
BUNDLE_VERSION
Current bundle format version.
SHA256_LEN
Length of a SHA-256 digest in bytes.