# `PtcRunner.Kernel.ApplicationPackage`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/kernel/application_package.ex#L1)

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.

# `t`

```elixir
@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()) =&gt; 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()) =&gt; binary()}
  },
  contracts: %{
    input: PtcRunner.Kernel.ValueContract.t() | nil,
    result: PtcRunner.Kernel.ValueContract.t() | nil,
    phase_returns: %{required(binary()) =&gt; 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()) =&gt; :local | :library},
  workflow_components: [PtcRunner.Kernel.Component.t()]
}
```

# `acquire_directory`

```elixir
@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`

```elixir
@spec acquire_memory(binary(), %{required(binary()) =&gt; 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`

```elixir
@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`

```elixir
@spec request_memory(binary(), %{required(binary()) =&gt; 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?`

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

Checks the package's in-VM construction attestation.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
