PtcRunner.Kernel.ComponentOverride (PtcRunner v0.14.0)

Replaces one already-selected component with trusted candidate source.

This is host CLI authority, not manifest authority. A manifest cannot name an override, and a generated program cannot produce one: the descriptor arrives only through --component-override-descriptor, and its source is read from a path confined to the descriptor's own directory. Evaluating a candidate is a deliberate operator act, so the candidate bytes must not be reachable through anything a run can influence.

The descriptor carries a required target naming either the workflow or one exact mission, plus component_id, base_source_hash, source_hash, and path. An optional closed provenance object records who authored the candidate. Provenance is operator-asserted and verified by nothing here: a run_id is a claim about origin, not evidence of it. It is kept out of identity/1 so content identity stays derived from content. Verification of the candidate itself is deliberately two-sided. The candidate source_hash proves the operator is compiling the bytes they believe they extracted; base_source_hash proves those bytes were derived from the component that is actually installed now, so a candidate written against a since-changed base is rejected instead of evaluated against the wrong baseline. Both are checked before the source reaches the compiler.

The source is opened once and the bytes that were hashed are the bytes that are compiled. The path is never reopened, so a file replaced between verification and compilation cannot substitute different source; the run either used the verified bytes or failed. Normal dependency, export, signature, and capability validation still applies afterwards, because an override changes which source compiles, never what compilation permits.

Nothing here writes. Materializing a candidate is a separate trusted host step, and promotion stays an explicit human decision.

Summary

Types

error()

provenance()

t()

Functions

apply(components, override)

Applies one verified override to a selected component list.

attribution(component_override)

Returns the authorship attribution an artifact records beside the identity.

hash(source)

Hashes component source with the descriptor's sha256: convention.

identity(override)

Returns the safe identity an artifact binds a candidate trial to.

load(path)

Loads and verifies one descriptor, returning the candidate source it names.

Types

error()

@type error() ::
  :invalid_override_descriptor
  | :invalid_override_source
  | :document_limit_exceeded
  | :json_depth_exceeded
  | :json_node_limit_exceeded
  | :override_source_hash_mismatch
  | :override_base_hash_mismatch
  | :override_component_not_selected
  | {:component_override_path, [PtcRunner.Kernel.CommandPath.segment()],
     :invalid_override_descriptor}

provenance()

@type provenance() :: %{optional(binary()) => binary() | boolean()}

t()

@type t() :: %PtcRunner.Kernel.ComponentOverride{
  base_source_hash: binary(),
  component_id: binary(),
  descriptor_bytes: non_neg_integer(),
  origin: binary(),
  provenance: provenance() | nil,
  source: binary(),
  source_hash: binary(),
  target: map()
}

Functions

apply(components, override)

@spec apply([PtcRunner.Kernel.Component.t()], t()) ::
  {:ok, [PtcRunner.Kernel.Component.t()], boolean()} | {:error, error()}

Applies one verified override to a selected component list.

The named component must already be selected: an override replaces source for a component the manifest chose, and never introduces one. Its declared dependencies are preserved, so a candidate cannot quietly acquire a new dependency — that would change the effective bundle beyond the source under evaluation.

attribution(component_override)

@spec attribution(t()) :: map()

Returns the authorship attribution an artifact records beside the identity.

This is deliberately separate from identity/1. That map is the override content record's payload, so anything added to it changes application_content_digest. Attribution is operator-asserted metadata about who authored a candidate, not part of what the candidate is, and content identity must not depend on an asserted timestamp or an acceptance flag.

Returns an empty map when the descriptor carried no provenance.

hash(source)

@spec hash(binary()) :: binary()

Hashes component source with the descriptor's sha256: convention.

identity(override)

@spec identity(t()) :: map()

Returns the safe identity an artifact binds a candidate trial to.

Hashes and the component ID are safe; candidate source never is.

load(path)

@spec load(binary()) :: {:ok, t()} | {:error, error()}

Loads and verifies one descriptor, returning the candidate source it names.

path resolves against the invoking process working directory. The source path inside the descriptor resolves against the descriptor's canonical directory and may not escape it.