# Primitive Ops vs Pluggable Ops

This section defines the execution boundary between deterministic kernel semantics and extensible domain execution.

It preserves:

* Kernel determinism
* Store-neutral traceability
* Backend substitutability
* Observational equivalence

---

# 1. Terminology

## 1.1 Kernel / Primitive Op

A **Kernel Op** (Primitive Op) is an operation defined in:

`OPREG/PEL1-KERNEL`

It is part of the `PEL/1-CORE` contract.

Kernel ops define fixed, deterministic semantics and are considered part of Amduat’s invariant semantic core.

---

## 1.2 Pluggable Op

A **Pluggable Op** is an operation defined outside `OPREG/PEL1-KERNEL`.

It is not part of `PEL/1-CORE`.

Its execution semantics:

* Are versioned independently
* May be effectful
* Are governed by profile or deployment policy
* Must emit execution artifacts for traceability

Pluggable ops extend behavior without extending the kernel.

---

# 2. Kernel / Primitive Ops

## 2.1 Properties

Kernel ops:

* Are defined in `OPREG/PEL1-KERNEL`
* Are pure and deterministic
* Have no side effects
* Depend only on explicit inputs
* Produce canonical artifacts
* Have stable semantics governed by spec revision

Kernel ops are portable across all backend tiers.

They cannot:

* Access external systems
* Read hidden state
* Depend on environmental configuration
* Produce nondeterministic outputs

---

## 2.2 Examples

* `bytes.concat`
* `bytes.slice`
* `hash.asl1_256`

These operations:

* Operate solely on canonical encoded inputs
* Produce deterministic outputs
* Are observationally equivalent across implementations

---

# 3. Pluggable Ops

Pluggable ops enable domain-specific execution without extending the kernel.

They may:

* Invoke LLMs
* Execute SSH commands
* Configure infrastructure
* Perform device operations
* Call external APIs

They are not part of the core semantic contract.

---

## 3.1 Properties

Pluggable ops:

* Are defined in external registries
* May be effectful
* May interact with external systems
* May be nondeterministic
* Must produce execution artifacts
* Must remain observationally separable from kernel semantics

They extend behavior while preserving traceability.

---

# 4. Execution Artifact Model

Every pluggable op MUST emit execution artifacts to ASL.

These artifacts preserve determinism at the semantic layer, even if the effect itself is nondeterministic.

## 4.1 Required Artifacts

At minimum:

### 1. ExecutionIntent

Declares:

* Target
* Parameters
* Configuration
* Version of pluggable op

Represents the desired action.

---

### 2. ExecutionReceipt

Confirms:

* Action dispatch
* Acceptance by executor
* Execution attempt metadata

Represents the attempt.

---

### 3. ExecutionOutput

Captures:

* Stdout/stderr
* Returned data
* Produced artifacts
* Exit codes

Represents the immediate result.

---

### 4. ExecutionObservation (Recommended)

Captures:

* Observed external state
* Post-condition checks
* Environment validation

Represents the verified outcome.

---

All execution artifacts:

* Are canonical ASL artifacts
* Are immutable
* Derive identity via `ENC/ASL1-CORE` + `ASL/1-CORE` + `HASH/ASL1`
* Participate in TGK projection

---

# 5. Traceability Requirements

All pluggable ops MUST be traceable in TGK by linking:

* `ExecutionIntent → ExecutionReceipt`
* `ExecutionReceipt → ExecutionOutput`
* Optional: `ExecutionOutput → ExecutionObservation`

These links are created via EdgeArtifacts written to ASL.

This ensures:

* Deterministic graph projection
* Provenance recoverability
* Replay safety
* Auditability

Even if external execution is nondeterministic, the trace is deterministic.

---

# 6. Governance Boundary

The boundary between kernel and pluggable ops is strict.

## 6.1 Kernel

* Small
* Deterministic
* Slow-moving
* Versioned with PEL core
* Subject to formal governance

## 6.2 Pluggable

* Extensible
* Fast-moving
* Policy-scoped
* Profile-scoped
* May be deployment-specific

No pluggable op may redefine kernel semantics.

---

# 7. Interaction with Backend Plug-in Model

This execution model aligns with the No Semantic Drift Rule:

* Kernel ops are invariant across all backends.
* Pluggable ops must emit artifacts.
* Backends must treat execution artifacts as ordinary ASL artifacts.
* TGK projection must remain deterministic.

Backend-specific optimizations must remain observationally equivalent to the artifact graph defined by execution artifacts.

---

# 8. Design Outcome

This separation:

* Preserves deterministic core semantics
* Enables real-world execution
* Prevents semantic leakage into infrastructure
* Maintains backend substitutability
* Ensures enterprise-grade auditability
* Supports edge and embedded deployments

Primitive ops define what Amduat *is*.
Pluggable ops define what Amduat *does*.