9.1. morloc-nexus file

morloc-nexus file plays the role of the UNIX file utility for Morloc-compatible data files. It recognises morloc packets (data-packet, call-packet, stream-packet, ping-packet), JSON, MessagePack, CSV, Arrow IPC, Parquet, ASCII / UTF-8 text, and empty files.

Default output is exactly one line per input file, formatted as <path>: <type> key=value …​. The stream is grep / awk / sort friendly: morloc-nexus file * | wc -l always equals the number of input files.

For example:

$ morloc-nexus file data.packet log.stream data.json data.mpk people.csv README empty.bin
data.packet: data-packet source=mesg format=msgpack schema="as" payload=1024 metadata=64 total=1120
log.stream: stream-packet schema="ad8" state=final status=closed subpackets=42 elements=524288 payload_full_size=8388608 payload_wire_size=524288
data.json: json
data.mpk: msgpack
people.csv: csv columns=3 delimiter=","
README: text encoding=ascii
empty.bin: empty

For morloc packets, classification is magic-byte based and seek-only, so even a multi-gigabyte CALL or STREAM packet costs a few hundred bytes of I/O. The on-disk file size is checked against the size declared in the packet header by default; truncated or oversize packets are reported and exit non-zero.

9.1.1. Stream packets

Stream-packet output carries the footer’s summary when one is present. state=final marks a cleanly closed stream (final footer + end-of-file tail present); state=temp marks an intermediate mid-stream footer written by an in-progress @close; state=missing marks a stream whose writer exited before writing a footer.

For state=missing files, morloc-nexus file runs a bounded forward scan of the sub-packet headers to report a best-effort subpackets=N and elements=N count. The scan is capped at 10 000 sub-packets (MORLOC_FILE_MAX_SCAN_SUBPACKETS to override); when the cap is hit the counts carry a trailing + and the file is flagged as truncated at the scan boundary. Scan results annotate the state=missing line but are diagnostic only: the file is left untouched. morloc-nexus view reuses the same scan to open the file through IStream or the pattern walker.

For the remaining formats, classification reads up to one kilobyte of the file and feeds it through the same parsers the runtime uses on real ingest.

9.1.2. Options

-F, --no-file

Suppress the <path>: prefix.

-D, --no-description

Suppress every key=value field; keep only the type token. -FD combined yields a clean type stream for programmatic use.

-v, --verbose

Break the one-line rule. CALL packets emit one indented arg[i]: data-packet …​ line per argument. CSV files emit one indented <name>:<type> line per column, with type inferred as one of int, float, str, bool, date, time, or other. STREAM packets emit the extended footer diag (writer pid, flush timestamps, oversize count, largest sub-packet, EOF tail window).

-n, --bytes SIZE

Bytes read for content-based detection. Accepts a K / M / G suffix. Default 1k. Morloc-packet detection always uses just the 32-byte header regardless.

--json

Emit one JSON object per file. JSON output is unaffected by -F / -D / -v and always includes the full structure, including CSV column names and types.

--validate

After classifying, fully load each file through the exact same loader the run subcommand uses, then discard the result. Appends validated=yes, validated=no error="<msg>", or validated=structure-only. If file --validate passes, run (or view) reading the same file will not fail at the load stage.

--schema STRING

Morloc schema used by --validate for inputs that don’t embed one. Ignored without --validate.

9.1.3. Verbose example

$ morloc-nexus file -v people.csv
people.csv: csv columns=3 delimiter=","
  name:str
  age:int
  city:str

$ morloc-nexus file -v call.packet
call.packet: call-packet midx=42 entrypoint=local nargs=3 payload=72 total=104
  arg[0]: data-packet source=mesg format=msgpack schema="i4" payload=4
  arg[1]: data-packet source=mesg format=msgpack schema="as" payload=16
  arg[2]: data-packet source=rptr format=voidstar schema="ad8" payload=8

$ morloc-nexus file -v log.stream
log.stream: stream-packet schema="ad8" state=final status=closed subpackets=42 elements=524288 payload_full_size=8388608 payload_wire_size=524288
  diag_version=1
  writer_pid=12345
  n_oversize_subpackets=0
  writer_start_time=1720000000
  first_flush_time=1720000001
  last_flush_time=1720000042
  largest_packet_uncompressed=262144
  largest_packet_idx=17
  tail_window=[...]