// calogArchive.h -- calog compression + archive library, built on libarchive.
//
// Two orthogonal capabilities, available to every engine. All data is a binary-safe string
// (embedded NULs preserved); a per-transfer cap (ARC_MAX) guards against a decompression bomb.
//
//   One-shot raw codecs (whole buffer, in memory):
//     compress(data, filter [, level])    filter: "gzip"|"bzip2"|"xz"|"zstd"|"lz4"|"compress"|"none"
//     decompress(data [, filter])         filter auto-detected from the magic bytes if omitted
//
//   Archive read (over the shared typed handle table):
//     archiveReadOpen(bytes)      -> handle   (whole archive already in memory)
//     archiveReadOpenFile(path)   -> handle   (streams from disk)
//     archiveReadNext(handle)     -> entry map | nil at end
//                                    entry: { name, size, mode, mtime, type[, linkname] }
//     archiveReadData(handle)     -> bytes    (current entry's data, whole, capped at ARC_MAX)
//     archiveReadClose(handle)
//
//   Archive write:
//     archiveWriteOpen(format, filter [, level]) -> handle
//         format: "tar"|"pax"|"ustar"|"gnutar"|"cpio"|"zip"|"7zip"|"iso9660"|"ar"|"mtree"
//         filter: "none"|"gzip"|"bzip2"|"xz"|"zstd"|"lz4"|"compress"
//     archiveWriteEntry(handle, name, data [, opts])   opts map: { mode, mtime, type }
//     archiveWriteFinish(handle)  -> bytes    (closes + returns the whole archive; frees the handle)
//
// The natives are INLINE (they run on the calling context's thread, stalling only that actor).
// Each archive handle is used by exactly one context at a time (its owner) and closed by exactly
// one context -- calog does not serialize a single handle across contexts. libarchive needs no
// process-wide init; register only builds the handle table, shutdown tears it down on last use.

#ifndef CALOG_ARCHIVE_H
#define CALOG_ARCHIVE_H

#include "calog.h"

// Register the archive/compression natives on a runtime. Idempotent across runtimes.
int32_t calogArchiveRegister(CalogT *calog);

// Release the shared handle table once the last registered runtime unregisters.
void    calogArchiveShutdown(void);

#endif