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/.p64reader; 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
.hmcBundles. - 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(v4Q42EMF64) and.qac(v1qac\0\0\0\0\0) entries embedded inside.hmcbundles. - species_
meta - Domain metadata schemas for
.hmcholistic entity digital twins. - stream
- Bounded QBDL streaming admission. Structural checks do not confer authority.
- streaming_
hydration - Byte-Backed WASM
.q42Host Seam, Progressive Range-Streamed.hmcDelivery, Webizen-Governed Worker Pool & Hardware Texture Transcoding Pipeline. - streaming_
loader - Progressive HTTP Range / OPFS slice streaming loader for
.hmcbundles. - variant_
matrix - Multi-Model Variant Matrix & Digital Twin Family Manifest for
.hmcBundles.
Structs§
- Bundle
Entry - 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-entrymeta(a nested CBOR blob whose schema is agreed by the producer/consumer of a given bundlekind— 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;metacarries any domain semantics. - Bundle
Mmap - Open a
.hmcbundle from disk viammapfor zero-copy access (native). - Bundle
Read Limits - Caller-owned cold admission limits.
decoded_index_bytesis 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. - Bundle
Reader - A parsed, integrity-checked view over a
.hmcbundle’s bytes. Borrows the input;get/segmentreturn slices into it (zero copy). - Bundle
Writer - Accumulates intact files and serialises them into a
.hmcbundle.
Enums§
- Bundle
Error - An error building or reading a
.hmcbundle.
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/.10dfiles, so their own segment offsets stay aligned andmmap/ zero-copy segment access into an entry is unaffected. This matches thePagealignment tier of thecontainer_10dwriter andp64_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→.hmcrename (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.