PtcRunner.Kernel.InspectionArtifact (PtcRunner v0.14.0)

Copy Markdown View Source

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

unsupported_schema_error()

@type unsupported_schema_error() ::
  {:unsupported_inspection_schema_version,
   %{artifact_version: integer(), supported_version: pos_integer()}}

Functions

load(path, opts \\ [])

@spec load(
  binary(),
  keyword()
) :: {:ok, [map()]} | {:error, atom() | unsupported_schema_error()}

Loads one exact fixed artifact with optional lower aggregate and per-record limits.

persist(path, records, canonical_events)

@spec persist(binary(), [map()], [map()]) :: :ok | {:error, atom()}

Validates and atomically persists one previously absent artifact.

preflight_destination(path)

@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.

validate_correlations(records, events)

@spec validate_correlations([map()], [map()]) ::
  :ok | {:error, :inspection_correlation_missing}

Validates every record identity and correlation against one canonical event set.