PtcRunner.Kernel.ApplicationPackage (PtcRunner v0.15.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 and interns identical source binaries by qualified SHA-256 so workflow and mission catalogs share one BEAM binary. 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.v3\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, and raw named phase-return contract 0x08. Component records use workflow/<id> or mission/<mission-name>/<id>; input and result contract names are input and result; phase-return contract records use their declared contract name. 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,
    phase_returns: %{required(binary()) => binary()}
  },
  contract_prompt_hashes: %{result: binary() | nil, phase_returns: map()},
  contract_prompt_projections: %{result: term() | nil, phase_returns: map()},
  contract_sources: %{
    input: binary() | nil,
    result: binary() | nil,
    phase_returns: %{required(binary()) => binary()}
  },
  contracts: %{
    input: PtcRunner.Kernel.ValueContract.t() | nil,
    result: PtcRunner.Kernel.ValueContract.t() | nil,
    phase_returns: %{required(binary()) => PtcRunner.Kernel.ValueContract.t()}
  },
  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, :component_override_descriptor, :repl_interactive_loop, and :omit_input. Pass omit_input: true to skip declared or caller-selected input. Unknown and duplicate options fail before the application source is opened. Live run-request adapters reject :omit_input and :repl_interactive_loop.

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 :installed_limits, :input_authority, :input, and :component_override_descriptor, 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. :omit_input and :repl_interactive_loop are package-acquisition flags and are rejected here.

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.