PtcRunner.Kernel.InspectionArtifact.Format (PtcRunner v0.15.0)

Copy Markdown View Source

Physical V1 contract for a sealed private inspection artifact.

The layout is:

16-byte versioned header
length-framed deterministic JSON evidence
192-byte terminal footer

Multibyte integers are unsigned big-endian. Offsets are absolute. A reader rejects a size that does not match the opened file, a header/footer version mismatch, overlap, gaps, or trailing bytes before following any range.

Summary

Types

footer()
versions()

Format and schema versions read without committing to a field layout.

Functions

artifact_digest(header, evidence, footer)
decode_footer(arg1)
decode_footer_versions(arg1)

Reads a footer's declared versions without requiring the current ones.

decode_header(arg1)
decode_header_versions(arg1)

Reads a header's declared versions without requiring the current ones.

encode_footer(footer)
encode_frame(payload)
encode_header()
footer_magic()
footer_size()
format_version()
frame_payload_offset(frame_offset)
header_magic()
header_size()
identity_sha256(value)
schema_version()
unsigned_footer(footer)

Types

footer()

@type footer() :: %{
  total_bytes: non_neg_integer(),
  evidence_offset: non_neg_integer(),
  evidence_bytes: non_neg_integer(),
  record_count: non_neg_integer(),
  first_sequence: non_neg_integer(),
  last_sequence: non_neg_integer(),
  run_id_sha256: binary(),
  trace_id_sha256: binary(),
  evidence_sha256: binary(),
  artifact_digest: binary()
}

versions()

@type versions() :: %{format_version: pos_integer(), schema_version: pos_integer()}

Format and schema versions read without committing to a field layout.

Functions

artifact_digest(header, evidence, footer)

@spec artifact_digest(binary(), binary(), footer()) :: binary()

decode_footer(arg1)

@spec decode_footer(binary()) :: {:ok, footer()} | {:error, :malformed_source}

decode_header(arg1)

@spec decode_header(binary()) :: {:ok, :header} | {:error, :malformed_source}

decode_header_versions(arg1)

@spec decode_header_versions(binary()) ::
  {:ok, versions()} | {:error, :malformed_source}

Reads a header's declared versions without requiring the current ones.

decode_header/1 matches this version's constants, so it cannot tell an artifact written by another version from a corrupt one. A bounded metadata probe must report those two states differently, and the magic plus the two version fields sit at fixed offsets for every version of the container.

encode_footer(footer)

@spec encode_footer(footer()) :: binary()

encode_frame(payload)

@spec encode_frame(binary()) :: {:ok, binary()} | {:error, :invalid_frame}

encode_header()

@spec encode_header() :: binary()

format_version()

@spec format_version() :: pos_integer()

frame_payload_offset(frame_offset)

@spec frame_payload_offset(non_neg_integer()) :: non_neg_integer()

header_magic()

@spec header_magic() :: binary()

header_size()

@spec header_size() :: pos_integer()

identity_sha256(value)

@spec identity_sha256(binary()) :: binary()

schema_version()

@spec schema_version() :: pos_integer()

unsigned_footer(footer)

@spec unsigned_footer(footer()) :: binary()