Piglet Binaries

A Piglet Binary is a target-native PiG executable for one fixed Piglet composition. It delivers an agent application directly without creating another harness implementation.

A Piglet Binary is a carrier for a Piglet. It does not introduce another configuration schema.

Build a Binary

Validate the Piglet first:

pig piglet validate ./agents/reviewer.yaml

Build the executable:

pig piglet build ./agents/reviewer.yaml \
  --format binary \
  --out ./pig-reviewer

Run it directly:

./pig-reviewer

The build records the Piglet, its Resource closure, its component plan, the target, and verification information.

Sign a Binary

Create an Ed25519 author key once. Keep the private file secret and publish the .pub file:

pig piglet keygen ./reviewer-signing.key

Sign during the native build:

pig piglet build ./agents/reviewer.yaml \
  --format binary \
  --out ./pig-reviewer \
  --sign-key ./reviewer-signing.key

The signature covers every executable byte and a DSSE manifest that names the Piglet, target, PiG version, resolution record, component plan, components, and embedded files. The Binary embeds the public half of its author key and checks the signature before command dispatch. An altered signature, manifest, Piglet, record, component, or executable byte makes the Binary refuse to run.

Check a file without running it:

pig verify ./pig-reviewer
pig piglet verify ./pig-reviewer

pig verify reports a valid Piglet signature as ok and an unsigned file as n/a; because it also verifies arbitrary archives and data files, it applies the required-signature policy only after a Piglet signature block identifies the target. pig piglet verify is Piglet-specific and succeeds only when the file carries a valid signature. Both commands reject a signed file whose key is revoked, and Piglet Binary startup enforces the required-signature policy for unsigned Binaries.

Trust and policy are explicit local actions:

pig piglet trust add ./reviewer-signing.key.pub
pig piglet trust list
pig piglet trust revoke ed25519:<key-id>
pig piglet trust require on

A valid signature by the embedded author key proves that the file has not changed since that key signed it. It does not prove who controls the key. Add a reviewed public key to the trust store to attach local identity, and enable require on when every Piglet Binary must be signed by a trusted, non-revoked key.

Sigstore keyless provenance

An Ed25519 Piglet signature is offline artifact integrity and local trust policy. Sigstore keyless provenance is separate evidence that a named CI workflow built an artifact. A release workflow can publish GitHub build provenance, and the recipient can verify it explicitly:

pig verify --provenance \
  --repo acme/reviewer \
  --signer-workflow acme/reviewer/.github/workflows/piglet-release.yml \
  ./pig-reviewer

This command delegates to gh attestation verify, which checks the Sigstore bundle, certificate identity, and transparency-log inclusion. It requires the GitHub CLI and may contact GitHub's attestation service. PiG never performs this network check at startup. Startup signature verification remains offline.

What the Binary contains

A Piglet Binary always contains:

• the Stock PiG execution engine;
• one fixed Piglet;
• its resolution and component plan;
• every extension or native component marked as Binary materialized;
• verification data required at startup.

A Binary can still require external items when its plan declares them:

• an external MCP service;
• a secret value;
• a configuration file;
• an interpreted runtime;
• a component supplied by a release or required agent environment.

Do not describe a Binary as self-contained unless its record proves that none of these requirements remain.

Realization and materialization

Each executable component records two independent facts.

A subprocess component does not create a different Binary type. It remains part of the same Piglet application and component plan.

Fused Go extensions

A compatible Go factory can be fused into the Binary. PiG compiles the extension into the executable and starts it through the same registration contract used by subprocess extensions.

Advantages:

• one target-native executable;
• no target-side Go compiler;
• no extension process startup;
• no serialization cost for process placement;
• exact extension source included in the build closure.

Costs:

• the Binary must be rebuilt when the extension changes;
• the artifact is target specific;
• the extension shares the PiG process failure boundary;
• fused code requires stricter review;
• only compatible Go factories can fuse.

Fused behavior must match source subprocess behavior. Fusion is a delivery optimization, not a second extension API.

Subprocess extensions

A normal Piglet Binary can start exact subprocess components when its plan permits them.

Advantages:

• process failure isolation;
• support for Go, Rust, Python, Node, and native programs;
• independent heartbeat and cancellation handling;
• easier source development and reload.

Costs:

• process and IPC overhead;
• explicit runtime requirements;
• more lifecycle and transport handling;
• the Binary might not contain every required runtime.

A prebuilt native subprocess component can avoid a target-side compiler. An interpreted component still needs its recorded runtime.

External components

An external realization connects to a separately managed service. The Binary records the requirement but does not embed or operate that service.

Use an external realization for network services that have their own lifecycle, scaling, credentials, or deployment owner.

Require all extensions to fuse

A Piglet can reject subprocess fallback:

build:
  extensionRealization: fused

The build then requires every selected extension to be a fuse-compatible Go factory. If one extension resolves to a subprocess, the build fails and names that extension and the reason.

PiG Standard uses this requirement. Every extension added to PiG Standard must:

• use the public Go extension factory contract;
• work in source mode through the normal subprocess host;
• work as a fused component;
• pass the same behavior and lifecycle tests in both modes.

Startup verification

A Piglet Binary verifies its embedded Piglet, component closure, and optional Ed25519 signature before command dispatch. A signed Binary refuses to run when any executable or signature byte changes. An unsigned Binary reports unsigned and runs unless the local trust policy requires every Piglet Binary to carry a trusted signature.

Startup does not silently:

• install a Package;
• download a missing component;
• substitute a same-named executable from PATH;
• log in to a provider;
• weaken an environment requirement;
• replace a failed fused extension with a subprocess.

A missing or tampered requirement causes a clear failure.

Failure and recovery

Fusion and subprocess execution have different physical failure boundaries, but they use the same extension behavior contract.

For subprocess components, PiG provides bounded heartbeat, cancellation, crash detection, quarantine, reload, and replacement behavior. A failed replacement does not remove the last working extension set.

PiG does not automatically replay an interrupted tool or command. A replay could duplicate file changes, messages, or network actions. The caller decides whether an operation is safe to retry.

A fused extension cannot lose a process socket because it runs inside PiG, but it can still panic, block, or misuse resources. Fused extensions therefore require lifecycle, shutdown, and leak verification before release.

See Extensions for the complete tradeoff and recovery model.

Portability

Build one Binary per target:

build:
  targets:
    - linux/amd64
    - darwin/arm64
    - windows/amd64

Do not claim target support until the artifact passes native verification on that target.

A Binary built on one target does not make an external service, secret, or interpreter portable. The record keeps these requirements visible.

Source mode versus Binary mode

Related documentation

• Piglets
• Extensions
• Derivative harnesses
• Packages