Persists and loads one immutable private inspection JSONL artifact.
Destinations must end in .inspection.jsonl, must not already exist, and are
installed atomically with a hard-link create from a file inside a mode-0700
temporary sibling directory. The file is restricted to 0600 before
content is written or the hard link is published. The create fails when the
destination already exists; unlike a rename, it cannot replace an existing
artifact. Temporary cleanup after the link is best-effort and cannot turn a
committed publication into a reported failure. A relative destination is
anchored once before validation so a VM-wide working-directory change cannot
redirect later filesystem operations. Loading opens a raw descriptor,
revalidates its identity, and performs two exact whole-file reads through EOF
whose bytes must match. It rejects symlinks,
changed files, content above 16 MB, any record above 2,000,000 encoded bytes,
excessive structural depth, malformed lines, mixed identities, non-contiguous
sequences, and records outside the exact V8 vocabulary. Private records use
a required mission_name on mission-owned source and capability
records while forbidding it on workflow-owned records. Effective prelude
source is proven, not asserted: the prelude-source records of an
environment must name exactly the components the canonical run-started
projection lists, and their source hashes must reduce back to the bundle
identity that projection committed to. Self-consistent source a caller
computed for itself therefore cannot pass as the source that compiled. V8
joins at most one
static prelude-call analysis to each subordinate evaluation source and also
admits at most one strictly JSON terminal result whose self-hash must match
the successful canonical run-stopped event. A missing capability or
evaluation correlation is accepted only when the same canonical trace's
events-dropped marker and terminal usage agree on enough dropped events of
that exact type. The retained trace marker therefore identifies the
inspection artifact as partial; an existing but mismatched correlation still
fails closed.
A syntactically decoded artifact whose records uniformly declare another integer schema version is rejected with both the declared and supported versions. It is not validated against a deleted historical vocabulary.
Secure publication is supported on Unix hosts with POSIX-compatible mkdir
and id executables available on PATH; persistence fails closed when those
authority/mode primitives are unavailable, a physical or lexical ancestor
has an untrusted owner, or any ancestor is group/other-writable without
sticky-directory protection. Preflight also rejects a final parent whose
effective permission class lacks create access. The same structural-depth
ceiling applies before in-memory retention, persistence, and loading.
Summary
Functions
Loads one exact fixed artifact with optional lower aggregate and per-record limits.
Validates and atomically persists one previously absent artifact.
Read-only destination preflight using the same path rules as persist/3.
Validates every record identity and correlation against one canonical event set.
Types
@type unsupported_schema_error() :: {:unsupported_inspection_schema_version, %{artifact_version: integer(), supported_version: pos_integer()}}
Functions
@spec load( binary(), keyword() ) :: {:ok, [map()]} | {:error, atom() | unsupported_schema_error()}
Loads one exact fixed artifact with optional lower aggregate and per-record limits.
Validates and atomically persists one previously absent artifact.
@spec preflight_destination(term()) :: :ok | {:error, :invalid_inspection_path | :inspection_destination_exists | :inspection_destination_unavailable | :inspection_destination_unsafe | :inspection_persistence_failed}
Read-only destination preflight using the same path rules as persist/3.
Classifies common deterministic conflicts — an invalid path or suffix, an
existing file, symlink, or directory, or an unreadable location — before
expensive work such as provider discovery or model calls begins. It never
authorizes overwrite: a destination can appear after this check, so
persist/3's exclusive atomic creation remains authoritative, and a free
preflight does not promise the destination stays creatable.
Validates every record identity and correlation against one canonical event set.