Host Adoption Profile

Host Adoption Profile v1 is the narrow compatibility boundary for applications that integrate OpenMeta into high-throughput image processing or transcoding. It is host-neutral: the source may be memory, a file handle, a range-backed object, or another synchronous positional I/O service.

Runtime contract check

Include openmeta/host_adoption.h and compare the application header with the linked library:

#include "openmeta/host_adoption.h"

if (!openmeta::host_adoption_profile_matches(
        openmeta::kHostAdoptionProfileV1)) {
    // Reject the incompatible runtime before processing assets.
}

HostAdoptionProfile is a trivially copyable, allocation-free version record. It reports API contract versions, not format coverage. Use metadata_capability(...) for format/family support and inspect positional read completeness and diagnostics for each asset.

Stable v1 boundary

Contract

Stable surface

Positional source

RandomAccessSource, ranges, caller-owned windows/accounting, exact reads, and kRandomAccessSourceContractVersion.

Snapshot read

read_transfer_source_snapshot_random_access(...), its scratch/options/result types, complete(), and kReadTransferSourceSnapshotContractVersion.

Read diagnostics

collect_read_transfer_source_diagnostics(...), caller-buffered records and names/messages, and kReadTransferSourceDiagnosticsContractVersion.

Snapshot state and persistence

The decoded-store TransferSourceSnapshot contract and kTransferSourceSnapshotContractVersion plus bounded, transactional serialize_transfer_source_snapshot(...) and deserialize_transfer_source_snapshot(...) using canonical wire v1.

Flat host reconciliation

Stable FlatHost + ExportNamePolicy::Spec export names plus typed add/update/remove import, tombstones, transactionality, and kFlatHostImportContractVersion.

Codec operation schema

TransferAdapterOpKind, PreparedTransferAdapterOp, explicit target fields, and kPreparedTransferAdapterContractVersion.

Breaking a stable v1 shape or semantic requires a new contract version, a compatibility path, or an ABI-major transition. Format support may grow when existing result, limit, ownership, ordering, and residual semantics remain compatible.

Supported reconciliation sequence

  1. Read with read_transfer_source_snapshot_random_access(...).

  2. Require result.complete() when the workflow needs complete metadata, or collect and apply policy to structured diagnostics.

  3. Serialize when the snapshot must outlive source storage or cross a host object/process boundary.

  4. Deserialize transactionally.

  5. Export FlatHost names with ExportNamePolicy::Spec and retain source entry identities.

  6. Import changed values, explicit typed additions, and removals. Replace the snapshot store only after FlatHostImportResult::ok().

  7. Pass the reconciled snapshot to target preparation.

Import preserves entry positions, represents removals as Dirty | Deleted tombstones, and appends additions. Untouched complex metadata, provenance, duplicate order, and raw-carrier entry links remain intact.

Deliberate experimental boundary

Profile v1 does not stabilize:

  • low-level format-specific scanners, payload extractors, or decoders;

  • file-path, whole-byte-span, or build_transfer_source_snapshot(...) helpers;

  • prepare_metadata_for_target_snapshot(...), PreparedTransferBundle, adapter-view build/validation/emission, or bundle execution;

  • prepared payload/package serialization;

  • raw-carrier passthrough policy or broad byte-preserving carrier transfer.

The typed operation schema is stable so codecs do not parse route strings, but its current builders remain coupled to the experimental prepared-bundle model. Hosts using target preparation should pin and test an OpenMeta release until that construction boundary is stabilized separately.

Performance and concurrency

Positional callbacks are synchronous and must not throw. The stable positional path has no hidden retry, locking, scheduling, or whole-file materialization. Scratch, windows, limits, and accounting are caller owned; the returned snapshot owns its finalized metadata state.

Independent operations may share an immutable source only when concurrent_reads is true and the backing supports concurrent exact reads. Do not share mutable scratch, accounting, import results, prepared bundles, or writers between concurrent operations.