PtcRunner.Kernel.ApplicationPackage (PtcRunner v0.14.0)

Immutable, path-free application semantics and captured source closure.

Directory and memory adapters feed the same manifest decoder and bounded document source. The resulting package contains portable logical names, effective component bytes, compiled contracts, safe override identities, aggregate accounting, a semantic-runtime revision, and the canonical application_content_digest; it contains no application directory, file descriptor, reader callback, selected input, or input name.

Directory acquisition caches every referenced byte exactly once. Compilation never reopens a captured path. This prevents time-of-check/time-of-use drift within one acquired record, but it is not a transactional multi-file snapshot: trusted deployments must keep the application directory quiescent while its closure is acquired.

Content identity is SHA-256 over "ptc.application-content.v2\0", a big-endian u32 record count, and records sorted by kind byte then UTF-8 logical name. Each record is kind || u32(name-bytes) || name || u64(payload-bytes) || payload. The closed kinds are projected-manifest 0x01, effective-local-source 0x02, shipped-library-source 0x03, input-contract 0x04, result-contract 0x05, direct-dependencies 0x06, and verified-override identity 0x07. Component records use workflow/<id> or mission/<mission-name>/<id>; contract names are input and result. Duplicate kind/name pairs are invalid. Manifest, dependency, and override payloads use PtcRunner.Kernel.TypedCanonicalJSON; source and contract payloads retain their exact captured UTF-8 bytes. The complete framed projection is capped at 8 MiB, so selecting the same captured source under multiple component IDs charges its bytes for every semantic occurrence instead of amplifying one cached document without bound.

Summary

Types

t()

Functions

acquire_directory(path, opts \\ [])

Acquires one confined-directory application into a path-free package.

acquire_memory(manifest_name, documents, opts \\ [])

Acquires one trusted in-memory logical-name/bytes application.

request_directory(path, opts \\ [])

Acquires and seals one complete directory-backed run request.

request_memory(manifest_name, documents, opts \\ [])

Acquires and seals one complete memory-backed run request.

valid?(package)

Checks the package's in-VM construction attestation.

Types

t()

@type t() :: %PtcRunner.Kernel.ApplicationPackage{
  application_content_digest: binary(),
  attestation: binary() | nil,
  component_overrides: [map()],
  contract_behavior_hashes: %{input: binary() | nil, result: binary() | nil},
  contract_sources: %{input: binary() | nil, result: binary() | nil},
  contracts: %{
    input: PtcRunner.Kernel.ValueContract.t() | nil,
    result: PtcRunner.Kernel.ValueContract.t() | nil
  },
  document_bytes: non_neg_integer(),
  document_count: non_neg_integer(),
  entry: binary(),
  events: map(),
  installed_limits: PtcRunner.Kernel.Limits.t(),
  labels: map(),
  limits: PtcRunner.Kernel.Limits.t(),
  manifest: map(),
  missions: map(),
  providers: %{workflow: [map()], mission: [map()]},
  ptc_semantic_revision: binary(),
  workflow_component_kinds: %{required(binary()) => :local | :library},
  workflow_components: [PtcRunner.Kernel.Component.t()]
}

Functions

acquire_directory(path, opts \\ [])

@spec acquire_directory(
  binary(),
  keyword()
) :: {:ok, t(), PtcRunner.Kernel.ExecutionInput.t()} | {:error, term()}

Acquires one confined-directory application into a path-free package.

Options are exactly :installed_limits, :input_authority, :input, and :component_override_descriptor. Unknown and duplicate options fail before the application source is opened.

acquire_memory(manifest_name, documents, opts \\ [])

@spec acquire_memory(binary(), %{required(binary()) => binary()}, keyword()) ::
  {:ok, t(), PtcRunner.Kernel.ExecutionInput.t()} | {:error, term()}

Acquires one trusted in-memory logical-name/bytes application.

Options are exactly :installed_limits, :input_authority, :input, and :component_override. Unknown and duplicate options fail before the application source is opened.

request_directory(path, opts \\ [])

@spec request_directory(
  binary(),
  keyword()
) :: {:ok, PtcRunner.Kernel.RunRequest.t()} | {:error, term()}

Acquires and seals one complete directory-backed run request.

In addition to the directory-acquisition options, accepts exactly :inspection_capture, :result_projection, and :event_identity. The latter fixes both event IDs and is rejected when the manifest already owns either identity.

request_memory(manifest_name, documents, opts \\ [])

@spec request_memory(binary(), %{required(binary()) => binary()}, keyword()) ::
  {:ok, PtcRunner.Kernel.RunRequest.t()} | {:error, term()}

Acquires and seals one complete memory-backed run request.

In addition to the memory-acquisition options, accepts exactly :inspection_capture, :result_projection, and :event_identity. The latter fixes both event IDs and is rejected when the manifest already owns either identity.

valid?(package)

@spec valid?(term()) :: boolean()

Checks the package's in-VM construction attestation.